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SOFTWARE LICENSE AGREEMENT 


ACI grants you a non-transferable, non-exclusive license to use this | 


copy of the program and accompanying materials according to the 
following terms: 

LICENSE: 

You may: 

a) use the program on only one computer at a time; 

b) make one (1) copy of the program in machine readable form sole- 





ly for backup purposes, provided that you reproduce all proprietary | 


notices on the copy: 

c) physically transfer the program from one computer to another, 
provided that the program is used on only one computer at a time; 
and 


d) transfer the program onto a hard disk only for use as described | 


above provided that you can immediately prove ownership of the 
original diskettes. 

You may not: 

a) use the program in a network unless you pay for a separate 
license for each terminal or workstation from which the program will 
be accessed; 

b) modify, translate, reverse engineer, decompile, disassemble, cre- 


ate derivative works based on, or copy (except for the backup copy) 


the program or accompanying materials; 

c) rent, transfer or grant any rights in the program in any form or 
accompanying materials to any person without the prior written con- 
sent of ACI which, if given, is subject to the conferee's consent to 
the terms and conditions of this license; or 


d) remove any proprietary notices, labels or marks on the program 
and accompanying materials. ) 

This license is not a sale. Title and copyrights to the program, 
accompanying materials and any copy made by you remain with ACI 


TERMINATION 


Unauthorized copying of the program (alone or merged with other 
software) or the accompanying materials, or failure to comply with 
the above restrictions will result in automatic termination of this 
license and will make available to ACI other legal remedies. Upon 
termination you will destroy or return to ACI the program, accompa- 
nying materials and any copies. 


LIMITED WARRANTY AND DISCLAIMER 


THE PROGRAM AND ACCOMPANYING MATERIALS ARE PROVIDED 
“AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR 
IMPLIED. INCLUDING. BUT NOT LIMITED TO, THE IMPLIED WAR- 
RANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICU- 
LAR PURPOSE 





ACI does not warrant that the functions contained in the program will meet 
your requirements or that the operation will be unintemupted or error free. 
The entire risk as to the use, quality, and performance of the program is with 
you. Should the program prove defective, you, and not ACI, assume the 
entire cost of any necessary repair. 

However. ACI warrants the diskettes on which the program is fur- 
nished to be free from defects in materials and workmanship under 
normal use for a period of ninety (90) days from the date ot delivery to 
you as evidenced by a copy of your receipt. The duration of any 
implied warranties on the diskettes is limited to the period stated 
above. ACl's entire liability and your exclusive remedy as to the 
diskettes (which is subject to you returning the diskettes to ACI or an 
authorized dealer with a copy of your receipt) will be the replacement 
of the diskettes or, if ACI or the dealer is unable to deliver a replace- 
ment diskette, the refund of the purchase price and termination of this 
Agreement. 

SOME STATES DO NOT ALLOW LIMITATIONS ON HOW LONG AN 
IMPLIED WARRANTY LASTS SO THE ABOVE LIMITATION MAY NOT 
APPLY TO YOU. THIS WARRANTY GIVES YOU SPECIFIC LEGAL 
RIGHTS. YOU MAY ALSO HAVE OTHER RIGHTS WHICH VARY 
FROM STATE TO STATE. 

LIMITATION OF LIABILITY 

IN NO EVENT WILL ACI BE LIABLE FOR ANY DAMAGES, INCLUD- 
ING LOSS OF DATA, LOST PROFITS. COST OF COVER OR OTHER 
SPECIAL, INCIDENTAL, CONSEQUENTIAL OR INDIRECT DAM- 
AGES ARISING FROM THE USE OF THE PROGRAM OR ACCOM- 
PANYING MATERIALS, HOWEVER CAUSED AND ON ANY THEORY 
OF LIABILITY. THIS LIMITATION WILL APPLY EVEN IF ACI OR 
AUTHORIZED DEALER HAS BEEN ADVISED OF THE POSSIBILITY 
OF SUCH DAMAGE. YOU ACKNOWLEDGE THAT THE LICENSE 
FEE REFLECTS THIS ALLOCATION OF RISK. SOME STATES DO 
NOT ALLOW LIMITATION OR EXCLUSION OF LIABILITY FOR INCI 
DENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE LIMITA- 
TION MAY NOT APPLY TO YOU. 

GENERAL 

This Agreement will be governed by the laws France. In any dispute 
arising out of this Agreement, ACI and you each consent to the juris- 
diction of both the state and federal courts of France. 

Use, duplication or disclosure by the U.S. Government is subject to 
restrictions stated in paragraph (c) (1) (ii) of the Rights in Technical 
Data and Computer Software clause at 252.227-7013. 

Licensor: ACI, 5 Rue Beaujon, 75008 Paris, France 

This Agreement is the entire agreement between us and super- 
sedes any other communications with respect to the program and 
accompanying materials. 

If any provision of this Agreement is held to be unenforcable, the 
remainder of this agreement shall continue in full force and effect. 





If you have any questions, please contact: ACI Customer 
Service, (33) 1 42 27 37 25 or write us at the above address. 
SIGN AND MAIL THE REGISTRATION CARD TODAY. 
Retum of the registration card is required to receive any product 
updates and notices of new versions or enhancements. 





AIl trade names referenced are the trademark or registered trade- 
mark of their respective holder. 

4D Compiler, 4th DIMENSION, and the 4th DIMENSION impossible 4 
logo are trademarks of ACI and ACIUS. Inc. 
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INTRODUCTION 


4D Compiler is the compiler for 4th DIMENSION. It provides numerous 
features and options that are not found in conventional compilers. The 
4D Compiler: 

m Systematically analyzes your database and provides extensive error 
diagnostic warnings and messages 

m Provides dynamic checking of the database while the compiled data- 
base is running 

m Supports interactive debugging with 4th DIMENSION 


m Compiles your procedures and scripts and generates true assembly 
code 
m Can generate code optimized for the 68020/30 and 68881/82 


m Can merge a compiled database with a copy of 4D Runtime, creating 
a stand-alone (double-clickable) application 


The database to be compiled is opened through the standard open-file 
dialog box. From then on, the compiler takes care of everything: It dupli- 
cates the structure file, systematically analyzes the database, generates 
descriptive and diagnostic reports, translates the copy’s procedures into 
machine language, and, possibly, generates an error file. You use the new 
structure file exactly the same way you use the original (uncompiled) 
structure file, except that you cannot enter the Design environment. 


Operating speed of a compiled database is dramatically increased, by a 
factor ranging from 3 to 1000, and even beyond for certain operations. 


4D Compiler generates true assembly code, adapted to the machine's 
microprocessor, 68000 or 68020/68030, while taking into account their 
mathematical coprocessor (68881 or 68882). 


NOTE: 4D Compiler compiles any database developed in Version 2. However, to use a 
compiled database you must have at least Version 2.1 of 4th DIMENSION. Contact 
ACIUS or ACI about obtaining an update. 
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Using 4D Compiler 


For optimal use of 4D Compiler, you should keep in mind the following 
points: : 

m Poorly-written procedures that do not perform well running in inter- 
preted mode may not do much better when compiled. Furthermore, 
poorly-written code may not be compilable: 4D Compiler detects the 
errors that prevent compilation. 


m A database that works well under 4th DIMENSION may not always be 
compilable. The 4th DIMENSION interpreter is tolerant of certain kinds of 
semantic and syntactic inconsistencies. 4D Compiler is exceptionally 
adaptable — as compilers rarely are — but it cannot be as flexible as an 
interpreter. This is due to the essential differences between interpreted 
and compiled modes. 


Unlike the 4th DIMENSION interpreter, the compiler requires that each 

variable be assigned exactly one data type. That is, the compiler must be 
able to positively type each variable. No ambiguity with regard to type is 
permitted. If a variable is used as a Real in one statement and as a Text 

variable in another statement, the compiler will generate an error mes- 
sage. 


You cannot change the type of a global variable anywhere in the data- 
base and the type of a local variable within the procedure or script in 
which it appears. 


Much of the work in preparing a database for compilation centers 
around meeting these conditions. You will find that the compiler con- 
tains several excellent diagnostic tools that aid in locating and fixing 
data typing problems. 


Sometimes you have latitude in how you type certain variables. 
Specifically, there are three types of numeric variables — real, integer, 
and long integer — and two types of alphanumeric variables — text and 
string. You can improve the performance of your compiled database by 
choosing the optimal type for each variable. Using integer variables can 
make procedures execute faster than using reals. Similarly, using fixed- 
length strings rather than text variables can make your code execute 
faster. 








How this Manual is Organized 


This manual includes the following chapters: 


w Chapter 1: Introduction. This chapter introduces you to the com- 
piler and explains the differences between compiled and interpreted pro- 
grams. 


w Chapter 2: User's Guide. This chapter describes the features and 
options available in 4D Compiler. 


m Chapter 3: Diagnostic Aids. This chapter describes three compiler 
tools that are useful when debugging a database: the Symbol Table, the 
Error File, and Range Checking. 


m Chapter 4:Preparing a Database for Compilation. This chapter 
describes the main principles you need to follow when writing a data- 
base that is to be compiled. 


m Chapter 5: Typing Guide. This chapter identifies the most frequent 
sources of typing conflicts. 


m Chapter6: Details about Certain Commands. This chapter provides 
additional information about certain commands in the language that are 
relevant only to compilation. 


m Chapter 7: Optimization Hints. This chapter contains some hints 
that can be used to optimize the performance of your code. 


Two appendices contain supplemental information about the compiler. 
Appendix A contains complete lists of messages displayed by the com- 
piler, with example code that produces each message. Appendix B con- 
tains information on customizing your application's icon. 


How to Use this Manual 


Read Chapters 1, 2, and 3 to learn how the compiler works. You may 
want to try to compile some of your databases as you explore the features 
and options described in Chapter 2. It is unlikely that your databases will 
be compilable on the first attempt; study the error messages and the sym- 
bol table generated by the compiler as you read the next group of chap- 
ters. Refer to Appendix A for explanations of error messages generated by 
the compiler. 


Read Chapters 4, 5, and 6 for detailed information on how to write code 
that is compilable. Finally, read Chapter 7 for hints on how to optimize 
compilable code. 
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Interpreted Mode versus Compiled Mode 


This section describes the fundamental differences between interpreted 
and compiled programs. 


The computer is a device in which commands are written using only 
“O”s and “1”s. The heart of the machine, the microprocessor, is incapa- 
ble of understanding any other language. This binary language is called 
machine language. 


A program written in any high-level computer language (C, Pascal, 
BASIC, 4th DIMENSION, and so forth) is first translated into machine lan- 
guage, so as to be understandable to the computer's microprocessor. 


There are two ways to do this: 


m The statements can be translated during execution; the program is 
said to be interpreted 


m The statements are translated as a whole, before program execution, 
in which case the program is said to be compiled 


Interpreted Mode 


When a series of statements is executed using an interpreter, the process 
can be broken down as follows: 


m The program reads a statement in the program’s own language 
m lt translates the statement into machine language 
m It executes the statement 


This cycle is executed for each of the statements in the program. When- 
ever you use 4th DIMENSION, the statements in your procedures and 
scripts are interpreted. 


Compiled Mode 


An application that uses a compiler works differently. A compiled pro- 
gram is translated in its entirety prior to execution. This process results 
in a new file that contains a set of statements in machine language. This 
set is saved for repeated use. That is, the translation is performed only 
once and the compiled version of the program is available for repeated 
execution. 


A disadvantage of this approach is that any debugging or modification 
of the program must be done on the original or source code. Then the 
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entire program must be recompiled. The compiled version of the pro- 
gram is not directly accessible to the developer. For this reason 

4D Compiler leaves your original database intact, so that you can make 
changes to it and recompile. 


The advantages to compiled mode are considerable, and are described in 
the section “Why Compile your Database?”, later in this chapter. 


4D Compiler and 4th DIMENSION 


4D Compiler compiles all global, file, and layout procedures, and all 
scripts. It generates a new structure file that is used in exactly the same 
manner as the original structure file. You can manage data in either the 
User or Runtime environments. The 4D Compiler retains your original 
structure file and creates a new (compiled) file for your use. 


When 4D Compiler finds errors or ambiguities, it usually cannot compile 
the database. It reports the errors in a text file. You correct the errors in 
the original (uncompiled) database and then recompile. 


Interactive Debugging 


A unique feature of 4D Compiler is that the error file can be used to 
debug a database interactively. Both the error file and the uncompiled 
database can be opened simultaneously in 4th DIMENSION. A new 

4th DIMENSION menu command, Next Compiler Error, automatically 
finds and highlights the next compiler error and displays the error mes- 
sage or warning. 


Why Compile your Database? 


The first benefit of compilation is, of course, speed of execution. There 
are two further benefits directly linked to compilation: 


m Systematic code check 


m Database protection 


Speed of Execution 


The increased speed is due to two characteristics of compiled code: 
= Direct code translation, once and for all 


m Direct access to variable and procedure addresses 


Direct and Final Code Translation 


4D Compiler translates your code and saves it as an executable file. The 
time required in interpreted mode to translate all the statements is saved 
whenever you use the database. 


Here is a simple case that illustrates this point. Take the case of a loop 
containing a sequence of statements that is repeated 50 times: 
For (i;1;50) 

‘Sequence of statements 
End for 
In an interpreted database each statement in the sequence is translated 
50 times. Using the compiler, the translation phase for each statement is 


eliminated. For every statement in the sequence, we save 50 translations. 


Here is another example. Suppose your database includes a Startup pro- 
cedure. This procedure is executed each time you enter your database. 


Afto comellatiga, peu cave tha Ha raquinad or tFANSIating (e GLAM 


procedure. 


These are only two examples. This enhancement actually affects all the 
statements in all procedures and scripts. 
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Direct Access to Variable and Procedure Addresses 


In interpreted procedures, variables are accessed through a name. There- 
fore, 4th DIMENSION needs to access the name in order to access the vari- 
able’s value. 


In the compiled code, the compiler attaches an address to each variable, 
writes the variable’s address directly in the code, and goes directly to that 
address. 


NOTE: Operations requiring disk access may not be affected, because their speed of op- 
eration is limited by the rate of transmission between computer and hard disk. 


A Comment about Comments 


Comments are not translated, so they do not appear in the compiled 
code. Thus, comments do not affect the execution time of a 
compiled database. 


Checking your Code 


Before attempting to compile a database, the compiler performs a logical 
and lexical check of your procedures and scripts. It systematically checks 
your code and notes possible ambiguities, whereas 4th DIMENSION does 
this when the procedure is executed. An important difference is that the 
compiler systematically checks all code, regardless of whether it is actu- 
ally executed in typical use. 


Suppose that one of your procedures contains a series of tests, as well as 
sequences of statements to be executed. It is unlikely that you would 
fully test for all cases if the number of tests were very large. In this 
instance, a syntax error in an untested case might not show up until an 
end-user encounters the case. 


When you compile a database, the entire database is scanned and each 
statement is analyzed. Where there is an abnormality, the compiler 
detects it and generates an error message or a warning. These messages 
are written to an error file that can be opened within 4th DIMENSION to 
facilitate interactive debugging. For complete information about interac- 
tive debugging, see the section “Using the Error File Interactively with 
4th DIMENSION” in Chapter 3. 


Protecting your Applications 

The compiled database is a copy of your original database, except that 
the compiled database shuts off access to the Design environment. The 
benefits are: 

m The database structure cannot be modified, intentionally or by acci- 
dent 


m Your procedures are protected 


A Practical Exercise 


Here is a brief tutorial exercise that demonstrates the increase in speed 
that the compiler provides. 


Installing 4D Compiler 


If you have not already done so, insert the 4D Compiler program diskette 
in your disk drive. Copy the 4D Compiler icon onto your hard disk. At 
the same time, transfer the Simulationf folder that comes with it. 


4D Compiler works on Macintosh computers that have at least one 
megabyte of RAM and a hard disk. 


NOTE: The minimum memory requirement for 4D Compiler is 700K. If you need to 
compile a large database (several megabytes), increase the memory size allotted to the 
compiler. This will provide better working conditions for compilation. 


Using the Macintosh's cache memory (accessible from the Control 
Panel) considerably speeds up the compiling process. Allow at least 700K 
for 4D Compiler, and some additional cache memory (32K to 

1 megabyte; anything in excess of 1 megabyte would be wasted). 


Running the Simulation 

The “Simulationf” folder on the diskette is a small 4th DIMENSION data- 
base. It is meant to provide a brief introduction to the compiler. 

1. Start 4th DIMENSION and open the Simulation database. 

The database opens in the Runtime environment. 


2. Choose Demonstration from the File menu. 


4th DIMENSION displays a list of records. You will now run a procedure 
that performs operations on its elements. 

















3. Click the Simulation button. 

The application executes a procedure that performs operations on reach 
value in the database. After completion of the operation, an alert dis- 
plays the time it took. 


The operation took 10 seconds 


NOTE: The time varies depending on the model of Macintosh you are using. 


4. Click OK and choose Quit from the File menu. 
4th DIMENSION quits and returns to the Finder. 


Compiling the Database 


In this section, you will compile the database and repeat the perfor- 
mance test. 


1. Start 4D Compiler by double-clicking the program icon. 
Before opening, 4D Compiler asks you to insert your program disk. 


Please insert the key disk 


NOTE: If the 4D Compiler key disk is already in the drive when the compiler is started, 
4D Compiler will not request the disk. 


2. Insert your program disk. 

The compiler ejects your master disk automatically and opens. 
3. Choose New from the File menu. 

An open-file dialog box is displayed. 





4. Open the database structure in the Simulationf folder: 


Database to compile 


Simulation 








The compiler displays the Options window. The options are described in 
Chapter 2, “User's Guide to the Compiler.” 









Compiling. 





Simulation | 


vi Database Nome Pc with Runtime 
No Runtime 
Error File Symbol Table 


No Error File 
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For this exercise, you don't need to use any of the options. 2 


5. Click the OK button. 
A save-file dialog box is displayed. 


* Simulation Pooch 
* Simulatian.data 


Name of compiled file 


Simula tion.comp 


(save) 








Before 4D Compiler can compile the database, you need to give the com- 
piled database a name. The default name is Simulation.comp. 
6. Click the Save button. 


4D Compiler asks you if you want to save the project. A project is a set 
of specifications in the Options window. You will find that projects are 








very convenient for “real life” work, but for this exercise, you do not 
need to save a project. 


7. Click No. 

4D Compiler starts the compilation process. During compilation, the 
4D COMPILER window is displayed. It shows the progress of the compi- 
lation and reports any errors Or warnings that it encounters. 






Copying Database Simulation 


Errors : 0 Warnings : 0 





The compiler notifies you that it did its job by displaying the message 
“End of Compilation” at the top of this window. 


8. Choose Quit from the File menu. 


Using a Compiled Database 


To use a compiled database you must have version 2.1 (or later) of 

4th DIMENSION. 

1. Start 4th DIMENSION, and open the Simulation.comp database. 
4th DIMENSION asks you for the data file belonging to the compiled data- 
base. 

2. Select the Simulation.data file. 

Using a compiled database is identical to using an uncompiled one. 

3. Go through the steps described in the section “Running the Sim- 
ulation” and compare performance times. 

You will note a dramatic speed increase. 
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Your Turn 


Once you complete this short exercise, you will want to try to compile 
one of your databases. 


Regrettably, your database may not be compilable on the first attempt. 
Because the 4th DIMENSION interpreter is more lenient than the com- 
piler, many databases that perform flawlessly in interpreted mode are 
not compilable on the first try. 


The compiler may find dozens of data typing conflicts. However, they 
are very easy to fix using the compiler's unique interactive debugging. 


The following chapter is a user's guide to the compiler. Following that 
chapter are several chapters that describe the process of debugging and 
writing code that is optimized for the compiler. 
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USER'S GUIDE TO THE COMPILER 


This chapter describes how to use 4D Compiler. It describes: 

m Using the compiler concurrently with 4th DIMENSION under Multi- 
Finder 

m 4D Compiler menus 

m Features and options that are available in the Options window 


m The compilation process 


4D Compiler options are organized around the concept of a project. A 
project is a group of selected options that you can save to disk. A project 
can be thought of as a style sheet for the compiler. 


Although you do not need to create a project to compile a database, a 
project makes the process of compiling, debugging, and recompiling 
quicker and easier. 


Using a project, you can: 

m Save the name of the compiled structure file 

m Create and save the error file and symbol table 

m Specify various options, including Merge with Runtime, Range 


Checking, Advanced Warnings, compatibility with the Script Manager, 
and target microprocessor. 


Each time you recompile a database using a project, 4D Compiler auto- 
matically generates the files you specify and uses the options you have 
invoked. For complete information about the options that are specified 
using a project, see “Compiler Options,” later in this chapter. 


Using 4D Compiler with 4th DIMENSION 


A database intended for compilation can be opened by both 

4th DIMENSION and the compiler. Using MultiFinder, you avoid having 
to quit 4th DIMENSION and reopen the database each time you want to 
compile it. 


To compile a database opened under 4th DIMENSION you only have to 
exit the Design environment by switching to the User or Runtime envi- 
ronments, and then switch to the compiler. 





During compilation you cannot use your database. Once compilation is 
completed, you can return to your database by switching to 
4th DIMENSION. 


The compiler can work in the background under MultiFinder. You can 
use another application while the compiler does its job. Even when you 
are in the Options window you can change applications, and the num- 
ber of applications you can open simultaneously is limited only by the 
amount of RAM in your Macintosh. 


4D Compiler Menus 

4D Compiler’s menu bar has three menus: 
m Apple 

w File 


a Edit 


The Apple menu includes the command “About 4D Compiler.” This 
command displays information about the compiler. 


The Edit menu is required for all Macintosh applications. It serves no 
purpose for 4D Compiler and is provided for use with desk accessories. 


Thus, the only menu that contains commands relating to the compiler 
is the File menu. It contains eight items. 


New 

Open 
Recompile 
Close 


Save 
Save as... 
Revert to saved 


Quit 





New 


Use this command to create a new project. The project specifies the data- 
base to be compiled, as well as all the compiling options you select. 





= 





When you choose this command, the compiler displays the standard 
open-file dialog box shown below. Use this dialog box to open the data- 
base to be compiled. 


Database to compile 


€ Scheduler ] 


















Options 


Compiling Scheduler 


a: Compiled Database Mame Merge vità Runtime 
fi None No Runtime 
Errer File Symbol Table 
No Error File No Symbol Table 
i] | Rosse Checking Asbi Script Manager 
dor | incompatibile 
| Advanced Warning Processor Type 
| of 68000 





Each of the eight icons in the Options window refers to a compiler 
option. These options are described in detail in the section, “Compila- 
tion Options,” later in this chapter. 


Open 


Use the Open command to open an existing project. Using a project, you 
can quickly perform several compilations of the same database, since the 
compilation environment is saved. 
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Create new 
project - 





When you choose Open, the standard open-file dialog box is displayed. 


Mi 


Open project 


Scheduler ] 


* Stheduler.pro] 





Open existing project 


When you select the project you want to open, 4D Compiler displays the 
Options window for that project. All of the settings for that project are 
displayed. 












Compiling Scheduler 


Merge with Runtime 
No Runtime 


sviene pene rase ne 
ad Soheduler symb 


NF. Compiled Database Mame 
[72 Scheduler comp 





Errer File 














If you choose Open from the File menu when you have no existing 
project, the New button allows you to open a database for compilation. Si. 


Recompiling a Database using a Project 


When you open an existing project, 4D Compiler uses all the options 
defined by the project. Some of these options create files that contain 
information about the results of the compilation (symbol table, error 
file, and so forth). Recompiling a project automatically recreates all the 
related files. If you want to keep files created by a prior compilation, be 
sure to save them elsewhere before recompiling. 


® 


For more information about these files, see the section, “Compilation 
Options,” later in this chapter. 
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Recompile 


Use the Recompile command to recompile a database that your are in 
the process of debugging. The Recompile command is intended for use 
during interactive debugging under MultiFinder. After you have fixed 
errors in 4th DIMENSION, you can switch to 4D Compiler and recompile 
your database by choosing Recompile from the File menu. For complete 
information on interactive debugging, see the section, “Using the Error 
File interactively with 4th DIMENSION” in Chapter SY 


Close 


Use the Close command to close the current project. If you haven't saved 
the current project and choose Close, the compiler displays a save-file 
dialog box, giving you a chance to save it. 


Save 


Use the Save command to save the current project, replacing the previ- 
ously saved version. 


Save As 


Use the Save As command to save a new project. This command displays 
the save-file dialog box that allows you to specify a new name for the cur- 
rent project. 


Revert to Saved 


Use the Revert to Saved command to return to the last saved version of 
the current project. 


Quit 


Use the Quit command to exit 4D Compiler. 
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Compilation Options 


The Options window includes eight icons. Each of these icons represents 
an option that can be selected or deselected. Click an icon to choose one 
of the actions it controls. A second click cancels the action of the first. 
AIl eight icons can be toggled. 


Each of the options is described in this section. 


Compiled Database Name 


Selected 





Use this option to name the compiled structure file. When you click this 
icon, the create-file dialog box is displayed. The default name for the 
compiled database is DatabaseName.comp. 


You can change this name as you wish. Click the Save button to save the 
name of the compiled structure file. After you name the compiled data- Pie: 
base, it is shown to the right of the icon in the Options window. 
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When the original database and the compiled database are located in the 
same folder, they must have different names. If you attempt to give the 
compiled database the name of the original one, the compiler displays 

the standard replace-file dialog box. You do not want to do this, because 
you need the original file for debugging. Even if you click Yes, 
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4D Compiler displays an error message and prevents you from overwrit- 
ing the uncompiled database. 





O The original file cannot be replaced. 


A compiled database is a replica of the original database; it operates 
exactly like the latter, except that you cannot access the Design environ- 
ment. Because you need access to the Design environment, 4D Compiler 
does not let you replace the original file. 


Merge with Runtime 


None _____ Pia Dai — Selected 


Use this option to merge your compiled database with a 4D Runtime and 
create a stand-alone (double-clickable) application. Before choosing this 
option, you must copy a 4D Runtime onto your hard disk. 


You must purchase a copy of 4D Runtime for each double-clickable 
application that you create or distribute. 


When you click this option, 4D Compiler displays an open-file dialog 
box. 
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@ 40 MOVER” 1.0.1 


« 4D Runtime 2.1 


@ 40 Tools” 2.0.10 
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Select the Runtime and click Open. When you return to the Options 
window, your choice of a merge with a Runtime is indicated by the name 


of the Runtime you selected. 


NOTE: You must use version 2.1 (or above) of 4D Runtime. 


IDE TO THE COMPILER 





During compilation, the compiler consolidates the Runtime with the 
database's compiled structure. It is not mandatory, of course, that you 
select this option. 


By default, the double-clickable application is given the generic applica- 
tion icon. You can customize this icon by following the directions in 
Appendix B. 


Error File 


rr 


Use this option to generate a text file that contains the list of errors and 
warnings detected during typing and compiling. This file can be opened 
within 4th DIMENSION and can be used for interactive debugging. 


None 





The error file also includes compilation warnings and the advanced 
warnings. For more information, see the section “Advanced Warning,” 
later in this chapter. 


When you click the icon, 4D Compiler displays the standard create-file Di 
dialog box. This file's default name is DatabaseName.ert. 
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Error File Name 





Use the default name if you want to use interactive debugging. Click the 
Save button. The name of the error file is shown in the Options window. ssi 


This file can be used in two ways: De 


w Asatext file, enabling you to keep written records of the messages 
produced by the compiler 

sm Within 4th DIMENSION, enabling you to debug your database in real 
time 


For complete information about this file, see Chapter 3 and the list of <p 
error messages in Appendix A. vo 








Symbol Table 


23 cn [P| Selected 


Use this option to generate a text file that contains the symbol table of 
your database. This file contains information concerning all the objects 
in the database to be compiled. This includes information on global vari- 
ables, their data types, and the name of the procedure from which the 
data type was determined. 


The symbol table also includes a list of your procedures and functions, 
the data types of their parameters, and, for functions, the data type of 
the value returned. 


When you click the icon, 4D Compiler displays the standard save-file 
dialog box. The file’s default name is DatabaseName.symb. 
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Symbol Table Name 





You can change this name if you wish. Click the Save button. The name 
of the symbol table is shown in the Options window. 


For complete information about the symbol table, see Chapter 3: 


Range Checking 


of Ta IR on 


Range Checking provides you with a particularly powerful set of diag- 
nostics. It monitors the execution of procedures while the compiled 


database is running. 


Range Checking does not display messages during compilation. The 
effects of this option are manifest only while you use the compiled data- 
base. It is provided because there are certain types of problems that can 
only be detected while the database executes. For complete information 
about Range Checking, see Chapter 3. 











Script Manager 


AS _______ Compatible 


Use this option whenever your database is to be used in conjunction 
with a 4th DIMENSION version that involves the Script Manager. 


Incompatible 





The Script Manager enables programs to function with alphabets and 
characters other than the latin ones, for instance: Japanese, Chinese, 
Arabic, or Hebrew. If your database will be used with a version of 

4th DIMENSION that works under Script Manager, select this option. 


Otherwise, you should not select Script Manager because your database 
would be slightly slower. 


Advanced Warning 


ic n e e] — On 2 


Use this option to generate more extensive diagnostic messages in the 
error file. There are two cases where it is especially valuable: 

m Your code is compilable, and you want your code to be of the highest i. pad 
quality possible Nr 
m Youare using statements about which the compiler cannot have an 

opinion. The compiler has made a sensible deduction considering what 

you have written, but you want to check whether its deductions match 

your intention. ssd: 


When this option is selected, the compiler generates informative mes- 
sages, not error messages. Such messages are automatically written in the ; 
error file. sd 


For complete information about this option, see Chapter 3: 
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(COMPIE 
Processor Type 
Mm) A] | —’—’68020/30 and 68881/82 


4D Compiler allows you to choose the microprocessor language you 
want to compile for. Your choice depends on the model of Macintosh on 
which the compiled database will run rather than the one on which it 
will be compiled. 


Some models of Macintosh use the 68000, such as the Macintosh Plus 
and SE, and others, such as the Macintosh II family, use the 68020/30 
and a mathematical coprocessor (68881/82). 


The 68020 and 68030 microprocessors are inherently more powerful 
than the 68000. This compiling option lets you take advantage of this 
feature. Moreover, 4D Compiler generates code that takes advantage of 
the math coprocessors that are installed with the faster microprocessors. 


A database compiled for a 68000 will run on computers equipped with a 
68000 and also on machines with the 68020 or 68030. However, a data- 
base compiled for a 68020/68030 will not run on a 68000-based com- 
puter. An error message would be displayed when you start the compiled 
database. 


If you are compiling for a Macintosh that is equipped with a third-party 
accelerator card that uses the 68020/30 but does not use a mathematical 
coprocessor, use the 68000 option. 


General Comments about Options 


None of the compiling options are mandatory. You can even start a Com- 
pilation without selecting any option. In this case, when you click the 
OK button, the compiler asks you to name the compiled database. It dis- 
plays the save-file dialog box. 
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You can also create a project without specifying the name of the com- 
piled database. When you start a compilation, 4D Compiler asks you to 
name the compiled database. 


Starting a Compilation 


Once your compiling options are selected, you start the compilation pro- 
cess by clicking the OK button in the Options window. From then on, 
the compiler works on its own, without your intervention. 


NOTE: If the database is password-protected, 4D Compiler prompts you for 
the Designer's password when you click OK. 


It would stop only if it couldn't find your external procedures. This point 
is described in the section “Compilation Process,” later in this chapter. 


If you click the Cancel button in the Options window, 4D Compiler 
closes the current project, and asks you whether you want to save it, if 
you have not done so already. 


Compilation Process 


Before compiling your database, make sure that it performs satisfactorily e 
in interpreted mode. Prepare the database for compilation by following at 
the guidelines in Chapter 4 of this manual, referring to later chapters in sc 
this manual, if necessary. si. 


When the compiler is in the process of compiling a database, it displays 
the 4D COMPILER window. It looks like this. 











4D COMPILER 
Typing Global Variables 
(P)ABOUT 


(P)CALCCALENDAR 
(P)CALCDAY 


(P)CENTERWINDOW 
(P)DELETE 





Errors : 0 Warnings : 0 


In the upper part of the window, the names of procedures and scripts 
scroll as they are processed by the compiler. 


{Pause — 
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In the lower part of the window, 4D Compiler displays a list of messages 
and, possibly, errors. Above this window are two counters: the error 
counter and the warning counter. The counters are automatically incre- 
mented throughout the compilation process. 


The Pause and Abort buttons enable you to interrupt the process, tempo- 
rarily (Pause) Or permanently (Abort). For more information, see the sec- 
tion “Interrupting the Compilation Process, ” later in this chapter. 

The main phases in the compilation process are: 

m Copying the database 

m Typing the variables 

m Compiling 

A small, moving icon on the left side of the upper window informs you 
of the status of the compilation. 


Copying the Database 


Only the database structure file (the file without suffix) is duplicated and 
compiled. This file contains the procedures and scripts of your database. 
The data file can be opened by either the compiled or uncompiled struc- 
ture file. 


If you selected the Merge with Runtime option, the compiler also dupli- 
cates the Runtime in this phase. 


Typing Variables 
In this phase, the compiler creates the symbol table for the compiled 
database. This phase consists of three passes: 


m Thedirective typing pass. This pass identifies the compiler directives 
and the array declaration statements and uses them to assign data types 
to variables and arrays. 

m The global typing pass. This pass types global variables that were not 
typed in the directive typing pass. 


m The local typing pass. This pass types the local variables. 


Each of the passes is indicated by an icon. If your procedures are small 
and/or if your computer is very fast, you will barely see them. 








Directive Typing Pass 


This pass is symbolized by the following icon: A 
In this pass, the compiler locates and stores the variables’ data types 
which are declared using compiler directives. In the same way it locates 
the arrays in the database and stores their data types. 


Global Typing Pass 
This pass is symbolized by the following icon: 2, 


In this pass, the compiler locates and stores the data types of the global 
variables that are not declared using compiler directives. The compiler 
types them according to their use. 


Local Typing Pass 
This pass is symbolized by the following icon: I, 


In this pass, the compiler locates and stores the data types of the local 
variables in the database. It uses compiler directives linked to the local 
variables, if they exist. Local variables that have no compiler directive are 
typed according to their use. 


General Considerations 


This is the phase in which the typing conflicts described in the Typing 
Guide (Chapter 5) are found. 


In cases of conflict, 4D Compiler uses the first occurrence of the variable, 
within each pass. Global procedures are analyzed in the order in which 
they are listed in the 4th DIMENSION procedure editor. 


Next to be analyzed are file procedures, layout procedures, and scripts 
attached to layouts, in the order of the files and layouts. 


If you change that order, either by sorting or by copying, the messages 
indicating type conflicts may be different, although the database, when 
executedì, is the same. 
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Conclusion of the Typing Phase 


Once typing is successfully completed, or if detected errors do not make 
it impossible to compile the database, the compiler automatically starts 
the compilation pass, as described in the next section. 


If general typing errors were found, 4D Compiler does not proceed with 
the compilation. Instead, it performs an additional typing pass. 


This pass is symbolized by the following icon: A 


These errors stem from two sources: 


m The compiler encountered two objects with the same name: a proce- 
dure and a variable; a variable and an external procedure; or two global 
procedures. When 4D Compiler finds two variables of different types 
with the same name, it records the data type conflict, but it does not stop 
at that level. 


m The compiler encountered a global variable that it cannot type. 


It is up to you to make corrections with the help of the messages pro- 
vided by the compiler. 


Compilation 


This is the pass in which 4D Compiler translates and saves your proce- 
dures in machine language. Here, 4D Compiler continues its search for 
errors. These are no longer typing errors, but compilation errors (syntax, 
various inconsistencies, and so forth). 


This pass is symbolized by the icon: C, 


If no errors were found in the compilation pass, the compiled database 
is created. 


If the compiler detects typing or compilation errors, then the compiled 
database cannot be created and you must first make the corrections. 


Iinterrupting the Compilation Process 


You can interrupt the compiler during typing and compilation by click- 
ing Pause or Stop at any time. 


Interruptions are useful whenever the compiler reports errors or warning 
messages. You can navigate among procedures when messages are 
attached to them. Navigation is performed in two ways: 


m Use the mouse to scroll the list and click the procedure you want 

m Use the Tab key to move from one procedure containing errors Or 
warnings to the next. Use Shift-Tab to move in the reverse direction. 
The compiler indicates errors and warnings in two ways, and uses them 
according to the nature of the message: 


m Whenit detects an error in a procedure or script, the compiler sets its 
name in bold 


m Whenit issues a warning about a statement in a procedure or script, 
the compiler sets its name in italics 


w If a procedure contains both errors and warnings, its name is set in 
bold. 


You can select the procedure by clicking. 











4D COMPILER 
End of Compilation 
(P)LOOKUP 


(P)MERGE RECORD 
(P)MERGE RECORDS 


(P)MODIFY EVENT 





Errors : ? Wernings : 15 






Warning in line 2 
If (Undefined($1)) 
Use of Undefined is not advised 








The error or warning is described in the lower panel. The three lines of 
the description are: 


m Line number in the procedure 
m Theline containing the error or warning 


w Anexplanation of the error or warning 








Using the Compiled Database 


You open the compiled database in the same way you open any 
4th DIMENSION database. However, you cannot enter the Design envi- 
ronment. 


If you requested an integration of yOur compiled database with a 
4D Runtime, double-click the application. 


The default icon for the application looks like this: ‘@ If you want to 
customize the icon, refer to Appendix B. 


Your compiled database executes just like your uncompiled one. 


NOTE: An uncompiled structure file and its compiled version can open the same data 
file. Specifically, you can use the two structure files on the same network and both can 
open the same data file. 
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The compiler produces three types of diagnostic aids that help make 
debugging easier: 

m Symbol Table. Analysis of the database is facilitated by the symbol 
table. Use it to find your way through your variables quickly. It is a valu- 
able tool for interpreting the error messages reported by 4D Compiler. 


m Error File. Debugging a database is facilitated by the error file that 
you can use as a text file or within 4th DIMENSION. 


m Range Checking. Range checking is a sophisticated tool for monitor- 
ing and controlling the execution of your procedures within your com- 
piled applications. 


This chapter describes these aids and contains complete information 
about how to use them. 


Symbol Table 


The symbol table is a text file that can be opened with any text or word 
processor. Information is presented in columns, with tabs separating 
each column. The symbol table contains complete information about 
the objects in your database. The document is divided into three parts: 


m Listof global variables 
m Listof local variables, in their procedure or script 


m List of global procedures and functions, with their parameters, if 
applicable I 


List of Global Variables 


Information about each global variable is presented in four columns: 

m The first column contains a complete list of global variables and 
arrays used in your database. These variables are listed in alphabetical 
order. 

m The second column contains the data type of each object. Types were 
established through compiler directive or determined from the use of the 
object. If the data type could not be determined, the column is empty. 
m The third column lists the number of dimensions, if the object is an 
array. 





m The fourth column contains a reference to the context in which the 
compiler established the object's data type. If the variable is used in sev- 
eral contexts, the context mentioned is the one used by the compiler to 


determine its data type. 


Here are the symbols used to identify where the variable name was 
found: 

m Ifthe variable was found in a global procedure, the procedure is iden- 
tified by the name you gave it in 4th DIMENSION, and preceded by (P). 
m Ifthevariable was found in a file procedure, the filename is given, pre- 
ceded by (FP). 

m lfthe variable was found in a layout procedure, the layout name is 
given, preceded by (LP). 

= Ifthe variable was found in a script, the script’ name is given, pre- 
ceded by layout name, filename, and by ($). 


m lfthe variable is an object in a layout and does not appear in any pro- 
cedure, formula or script, the name of the layout in which it appears is 
given, preceded by (L). 


Here is a list of global variables from a typical database. rifl. 




























1 dimension (P)LOOKUP 
3AADDR2 Text 1 dimension (P)LOOKUP 


ACITY Text 1 dimension (P)LOOKUP si 
@ACODE Long integer 1 dimension (P)LOOKUP _ ci 
ADDRESS Text (LP)[Contacts] LETTER 

ANAME Text 1 dimension (P)LOOKUP 

ASTATE Text 1 dimension (P)LOOKUP 54 3 
Bi Real (L)[Letters] SELECT LETTER * 

82 Real (L)[Letters] SELECT LETTER 

B3 Real (L)[Letters]. SELECT LETTER ' % 
B4 Real (L)[Letters]. SELECT LETTER tat - 
BACCEPT Real (L)[Contacts] Input : 

BADD Real (L)[Contacts] Contacts OUT 9 - 
BADDEVT Real (L)[Contacts] Contacts IN 9 3 
BADDRBOOK Real (L)[Contacts] Contacts OUT 9 sn 
BCANCEL Real (L)[Contacts]. Input 

BDELETE Real (L)[Contacts] Contacts IN 9 and 
BDELKW Real (L)[Contacts]. APPLY KEYWORD Ì 

DONE Real (L)[Contacts] ABOUT hand 

BFIND Real (L){Contacts] APPLY KEYWORD PR 
BFIRST Real (L)[Contacts] Input pa Enno 
BFIRSTPAGE Real (L)[Contacts] Input 

BLABELS Real (L)[Contacts] Contacts OUT 9 È 
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List of Local Variables 


The list of local variables is sorted by global procedure, file and layout 
procedure, and script, in the same order as in 4th DIMENSION. Only 
those procedures that use local variables are shown. 


Here is a list of local variables from a typical database. 






Contacts 11.5 mb 


Text 

Text 
(P)CAPITALIZE 
Real 

Pointer 

(p)Cat 

Text 

Text 

Text 

(P)CENTER WINDOW 


Real 
Real 


List of Procedures 


A complete list of your global procedures is given at the end of the file, 
with the data types of their parameters and, for functions, the returned 
result. This information is presented in the following format: 


Procedure name (parameter data type): result data type 


Here is a list of procedures. 


ADD EVENT 
ADD KETWORD(Text) 
ADD RECORDS 
pP edi ADDRESS BOOK 
Procedure APPLY KEYWORD 
Procedure CAPITALIZE(Pointer) 
function CAT(Text. Text) Text 
iP FINDOW(Real.Real.Real.Tert) 





Error File 


The error file contains messages that were generated during of compila- 
tion. The file can be used in two ways: 


m Asatext file, which can be opened with at text or word processor 


= Interactively, with 4th DIMENSION 


Types of Messages 


4D Compiler generates three types of messages: 
m General errors 
m Errors linked to a specific line 


m Warnings 


General Errors 


These are errors that make it impossible to compile the database. They 
appear at the top of the error file and above the list of procedures in the 
4D COMPILER window. 


È 4D COMPILER | COMPILER dui 


End of Compilation 











*** General Errors *** 
(P)ABOUT 
(P)ADD CONTACTS 


(P)ADD EVENT 
(P)ADD KEYWORD 





Errors : 7 Warnings : 15 
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When you click General Errors, the related messages are displayed in the 
lower panel, as shown below. 
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End of Compilation 









(P)ABOUT 
(P)ADD CONTACTS 
(P)ADD EVENT 

(P)ADD KEYWORD 


Errors : 7 Warnings : 15 






The type of DELAY 1s unknown 
This variable 1s used in the procedure (S)[Events].Event Dialog.Comple 





Pausp ) Stap ) 
There are two cases in which the compiler reports a general error mes- 
sage: 

m The data type of a global variable could not be determined 








m Two different kinds of objects have the same name 


In the first instance, 4D Compiler could not perform a particular typing 
anywhere in the database, and, in the second instance, 4D Compiler was 
unable to decide whether to associate a given name with one object 
rather than with another. 


These errors are called general errors because they cannot be linked to 
any specific procedure or script. Appendix A contains a list of general 
errors. 


Errors Linked to a Specific Line 


These errors are displayed in context — the line in which they were 
found — with an explanation. 


The compiler reports this type of error when it encounters an expression 
in which it sees an inconsistency, either data type or syntax related. 


Procedures or scripts that contain such errors appear in bold, in the 
upper window. When you select one of those procedures, information 
about all errors in the procedure are displayed in the lower panel, in the 
following manner: 

m Line number 

w Statement containing the error, as it appears in your procedure 


m Description of the error 
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Here is a typical error in a line of code. 


4D COMPILER 









End of Compilation 

















(S)Events] Event Dialog.Delay 
(S)lEvents]Event Dialog.Due Date 
(S)[Events] Event Dielog:Contact 
(S)fletters] SELECT LETTER Letter 
(St etterslEDIT LETTER Mergeltems 






Errors : ? Wornings : 15 







Error in line . 20 
SELECTION TO ARRAY([Letters]Name,Letter) 
Retyping of the variable LETTER from type Reel to type Text 





Appendix A of this manual contains the list of these errors. 


Warnings 


Warnings are not errors. Warnings do not prevent the database from Rs 
being compiled. They point out areas to which the compiler wishes to 


draw your attention because they have a potential for error. dd: 57 
Procedures or scripts in which warnings have been detected appear in Po MS 
italics in the upper window. When you select one of those procedures, mu 
the list of warnings are displayed in the lower panel. pe 
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End of Compilation 
(S)Events]. Event Dialog.Delay 


(S)[Events] Event Dialog.Due Date 
(S}Events] Event Dialog Contact 





(S)ILetters].SELECT LETTER.Letter 





Errors : ? Warnings : 15 







warning in line 16 
LIST TO ARRAY("Merge Fields",$me») 
Pointer in LIST TO ARRAY 





Stop ] 


The information is presented in the following order: 
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m Line number > 
m Statement to which the warning refers, as it appears in your proce- = 
dure 


m Explanation of the warning 
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If you had chosen the Advanced Warning option, other warnings would 
also be displayed. Appendix A contains a complete list of warnings. 


Using the Error File 
The error file can be used in two ways, as a text document, and within 
4th DIMENSION. 


Using the Error File as Text 


When you open an error file using a text editor, it looks like this. 


Errors 7 iarnings. 15 

=** Genera! Errors *** 

The type of DELAY is unknoesn 

This variable \s used in the procedure (S) Events]. Event 
Dialog Conpleted 


CPIINIT POP _UP 


Marning in line ' 

If ‘Undefined($2»)) 

Use of Undefined is not advised 
Marning in lina 2 

LIST TO ARRAV($3; $2») 

Pointer in LIST TO ARRAY 

The type of $4 is unknoen 


«PILOOKUP 
The type of $X :s unknoen 





The structure of the error file is as follows: 
m The number of errors and warnings is at the top of the file 


m The general errors are listed next 


m Allother errors and warnings are listed last, sorted by procedure or 
script, in the same order as in 4th DIMENSION 


These errors and warnings are listed using the following format: 
m The line number in the procedure 
m The line containing the error or warning 


m A diagnostic that describes the error 









v Design 
User vw 
Runtime 


Stop browsing error file 







Using the Error File Interactively with 4th DIMENSION 


You can use the error file to correct your errors interactively. This section 
describes how to do this. 


1. Run the compiler and generate the error file. 
To open it in 4th DIMENSION, you must place the error file in the data- 
base folder and use the default name that 4D Compiler suggests. 


2. Start 4th DIMENSION and open your uncompiled database in the 
Design environment. 

Two commands are automatically added to the Use menu for interactive 
debugging. The two commands are: Next Compiler Error and Stop 
Browsing Error File. 


3. Choose Next Compiler Error from the Use menu. 


4th DIMENSION automatically opens the first procedure or script in 
which 4D Compiler found an error or warning. 


D) Procedure: INIT POP UP 
of Undefmed 15 not advisec 


it_Undetmed 
LIST TO ARRAY($3,$2») 

End if 

M ($1»="") 
$2» =Fund im arrag($2»;$4.1) 


Else 
$2» =Find in array($2»;$1»,1) ‘choose the right element to be displayed 
End if 





At the top of the window the nature of the error or warning is described. 
In the procedure, the affected line is highlighted. 


4. Debug the error that the compiler spots. 
If the message is a warning, you may not need to modify your code. 
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5. Move to the next error or warning by choosing Next Compiler 


Error from the Use menu. 
The next error or warning is displayed. 





fi SEA Procedure: INIT POP UP 


‘arning Pomter n LIST TO ARRAY 











lf (Undefined($2,)) 
LISI 10 ARRAY ii 
| Ema if 

19 ($1»="") 
$2» =Find in array($2».$4.1) 

Else 

$2» =Find in arrayg($2»,$1 »,1) ‘choose the right element to be displayed 











In this manner, you can correct all errors quickly, without having to 
spend time locating each error manually. 


Use the Stop Browsing Error File command to end the debugging session. 
When you leave the Design environment, the error file is automatically 
closed. 


Range Checking 


While all the other options operate during the compilation process, 
Range Checking begins its work only when you run the compiled data- 
base. That is, you receive this set of messages while your compiled data- 
base is running. 


Range checking is an “in situ” controller; it evaluates the status of objects 
in the database at a given time. Here is an example of how Range Check- 
ing works. 


Suppose that you declared the array MyArray as Text. The number of ele- 
ments in MyArray may vary depending on the current procedure. 


Suppose you want to assign the value “Hello” to element 5 of MyArray. 
Therefore you write: 

MyArray{5}:="Hello" 

If at that time MyArray has 5 elements or more, everything is fine. 


Assignment proceeds normally. However, if MyArray has less than 
5 elements at that moment, your assignment no longer makes sense. 








A situation like this cannot be detected at compilation, because of the 
presupposition that the procedures are executing. The compiler would 
not know the circumstance in which this procedure is called. Only Range 
Checking enables you to monitor what is actually happening while your 
database is in use. 


In the example above, the compiler would display a message like this 
from within 4th DIMENSION. 





It is easy to see why Range Checking is especially valuable when arrays, 
pointers, and strings of characters are being processed. 


The messages displayed by the compiler when you request Range Check- 
ing are listed in Appendix A of this manual. 


How and When to Use Range Checking 


When you request Range Checking, your compiled database becomes 
substantially slower than it is without this option. Therefore, it should 
not be requested for the “final” compilation of a finished database. 


It should be used as an additional phase in the process of developing and 
debugging your databases. It is assumed that you will run a final compi- 
lation without Range Checking. 


The compiler's most obvious purpose is to speed up databases. An 
equally important goal is to help you in the enhancement of your appli- 
cation’s reliability. We therefore recommend that you consider a devel- 
opment phase that includes Range Checking. 








Diagnosing Anomalies 


This section provides some background information on the value of 
Range Checking. 


Suppose you notice anomalies in the running of your databases. Before 
you start speculating about their possible sources, remember the assis- 
tance provided by the compiler. 


Potential anomalies are: 


m 4th DIMENSION displays its own error messages. If possible, correct 
this error in your database according to instructions provided by 

4th DIMENSION. If the latter are too general, compile your database again 
with the Range Checking option. Retest your database. At the location 
where the 4th DIMENSION message was displayed, you will see a more 
informative message from the compiler. 


m Your compiled database does not perform exactly like your uncom- 
piled database. Take a closer look at the Advanced Warning messages. 
Possibly, you may want to add the Range Checking option. 


m Your database performs smoothly in interpreted mode. After compi- 
lation, an error creates a system crash or a return to the Finder. You find 
yourself in a situation typical of Assembler or Pascal programmers. If you 
are well versed in the use of a Macintosh debugger, this tool can help you 
find the name of the procedure in which you crashed. If you are not 
familiar with a debugger, a simpler solution is to recompile with the 
Range Checking option. Chances are good that your problem will be 
detected. 
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The 4th DIMENSION interpreter gives you a great deal of freedom in the 
way you can name variables and procedures. An interpreter can be more 
tolerant of certain types of conflicts and inconsistencies than a compiler. 


When writing a database for the compiler, you need to follow these basic 
principles: 

m Each variable, global procedure, and external procedure must have a 
unique name 

m Each variable must be assigned (implicitly or explicitly) exactly one 
data type 


These principles are, simply, good programming practice. They do not 
limit the operations that can be performed in compiled 4th DIMENSION 
databases. They are introduced only because it is essential that the com- 
piler be able to identify, without any ambiguity, each object in 

the database. 


The objects that are most likely to create ambiguities are variables. This 
chapter, therefore, is devoted to them. 


Ambiguities stem from two major sources: 
m Using the same name for two different variables 
m Assigning (implicitly or explicitly) different data types to the same 


variable 


Before creating the compiled database, the compiler makes extensive 
checks and, when it finds ambiguities, generates diagnostic messages 
that make it easy to debug databases that were not written with these 
guidelines in mind. 


Data Types of Variables and Arrays 


All variables have a data type. There are 11 data types for variables: Bool- 
ean, String, Date, Integer, Longint, Graph, Time, Picture, Real, Pointer, 
and Text. 


For Array type variables, there are 9 data types: Array Boolean, Array 
String, Array Date, Array Integer, Array Longint, Array Picture, Array 
Real, Array Pointer, and Array Text. 


CHAPTER 4 PREPARING A DATABASE FCR CCMPILATION 





The Symbol Table 


In interpreted mode, a variable can have more than one data type. This 
is possible because the code is interpreted rather than compiled. 

4th DIMENSION interprets each statement separately and comprehends 
its context. 


When you work in a compiled environment, the situation is different. 
While interpretation is performed line by line, the compilation process 
looks at a database in its entirety. The compiler’s approach is the follow- 
ing: 

m The compiler systematically analyzes the objects in the database. The 
objects are global, layout and file procedures, and scripts. 


m The compiler scans the objects to determine the data type of each 
variable used in the database, and it generates the table of variables and 
procedures (the symbol table) 


m Once it has established the data types of all variables, the compiler 
translates (compiles) the database. 


But it cannot compile the database unless it can determine the data type 
for each of the variables. 


If the compiler comes across the same variable name and two different 
data types, it has no reason to favor any particular one. In other words, 
to type an object and give it a memory address, the compiler must know 
the precise identity of that object, i.e., its name and its data type. The 
compiler determines its size from the data type. 


For every compiled database, the compiler creates a map that lists, for 
each variable, its name (or identifier), its location (or memory address), 
and the space it occupies (indicated by its data type). This map is called 
the symbol table. 


Typing Variables with 4D Compiler 


The most straightforward and unambiguous way to type variables is to 
use the compiler directive commands in the language. However, it is not 
necessary to use a compiler directive for every variable. 


4D Compiler is clever enough to free you from the drudgery of having to 
declare every variable in your database — something you need to do 
with conventional compilers. Whenever possible — as long as there is no 
ambiguity — 4D Compiler determines the type of a variable from the 
way it is used. 
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For example, if you write: 
V1:=12.5 
the compiler determines that variable V1 is data type Real. 


By the same token, if you write: 
V2:="This is a sample phrase" 
the compiler determines that V2 is a Text type variable. 


The compiler is also capable of establishing the data type of a variable in 
less straightforward situations. Here is an example: 

V1:=12.5 

V2:="This is a sample phrase" 

V3:=VI1 


Here, the compiler concludes that V3 is the same type as VI. 


Here is a similar example: 
V4:=2*V2 
Here, the compiler concludes that V4 is of the same type as V2. 


4D Compiler also determines the data type of your variables according 
to calls to 4th DIMENSION commands, and according to yOur procedures. 
For example, if you pass a Boolean type parameter and a Date type 
parameter to a procedure, 4D Compiler assigns the Boolean type and the 
Date type to the local variables $1 and $2 in the called procedure. 


When the compiler determines the data type by inference, it never 
assigns the limiting data types: Integer, Longint, or String. The default 
type assigned by 4D Compiler is always the widest possible. For example, 
if you write: 

Number:=4 

the compiler assigns the Real data type to Number, even though 

4 happens to be an integer. In other words, the compiler does not rule 
out the possibility that, under other circumstances, the variable’s value 
might be 4.5. 


If it is appropriate to type a variable as Integer, Longint, or String, you 
can do so using a compiler directive. It is to your advantage to do so, 
because these data types occupy less memory and performing operations 
on these data types is faster. 


Comnpiler Directives 


The 4th DIMENSION Language Reference contains a description of the fol- 
lowing compiler directive commands: 
C_STRING (length; variable1 {;...; variableN}) 
C_BOOLEAN (variable1 {;...; variableN}) 
C_DATE (variable1 {;...; variableN}) 
C_INTEGER (variable1 {;...; variableN}) 
C_TIME (variable1 {;...; variableN}) 
C_PICTURE (variable! {;...; variableN}) 
C_LONGINT (variable! {;...; variableN}) 
C_REAL (variable1 {;...; variableN}) 
C_POINTER (variable! {;...; variableN}) 
C_TEXT (variable1 {;...;variableN}) 


These commands enable you to explicitly declare the variables used in 
your databases. They are used in the following manner: 


C_BOOLEAN (Var) 
Through such directives you inform the compiler to create a variable Var 
that will be a Boolean. 


Whenever an application includes compiler directives, 4D Compiler 
finds them and, thus, avoids guesswork. A compiler directive has priority 
over deductions made from assignments or use. 


NOTE: There are ten compiler directives whereas there are eleven types of variables. 
There is no specific compiler directive for graphs since there can never be any ambiguity 
about the data type of a graph variable. 


When to Use Compiler Directives 


Compiler directives are useful on two occasions: 


m The compiler is unable to determine the data type of a variable from 
context 


m Youdo not want the compiler to determine a variable's type from use 


È: 











Cases of Ambiguity 


Sometimes the compiler cannot determine the data type of a variable. 
Whenever it cannot make a determination, 4D Compiler generates an 
appropriate error message. There are two major causes that prevent the 
4D Compiler from determining the data type: 


m Multiple data types 


m Unable to determine a typ® 


Multiple data types 


If a variable has been retyped in different statements in the database, the 
compiler generates an error that is easy to fix. 


The compiler selects the first variable it encounters and arbitrarily 
assigns the data type it had previously assigned to the next occurrence 
of the variable. 


Here is a simple example: 


Variable:=TRUE “in procedure A 

Variable:="The moon is green" ° in procedure B 

If procedure A is compiled before procedure B, the compiler considers 
the statement “Variable:="The moon is green” as a data-type change in a 
variable previously encountered. The compiler notifies you that retyping 
has occurred. It generates an error for you to correct. In most cases, the 
problem can be fixed by renaming the second occurrence of the variable. 


Unable to Determine a Data Type 


This case arises when a variable is used without having been declared, 
and within a context that doesn't provide information about its data 
type. Here, only a compiler directive can guide the compiler. 


This phenomenon Occurs primarily within two contexts: when pointers 
are used, or with a command with more than one syntax. 


m Pointers. A pointer cannot be expected to return a data type except 
its own. Consider the following sequence: 


Var1:=5.2 (1) 
Pointer:=»Vart” °(2) 
Var2:=Pointer»” °(3) 


Although (2) defines the type of variable pointed to by the pointer 
Pointer, the type of Var2 is not determined. During the compilation pro- 





cess, 4D Compiler is able to recognize a pointer, but it has no way of 
knowing to what type of variable it is pointing. Therefore, it cannot 
deduce the data type of Var2. A compiler directive such as 


C_REAL (Var2) 
is necessary. 


= Multi-syntax commands. When you use a multi-syntax command, 
the compiler cannot guess which syntax and parameters you have 
selected. Here is an example: 


The FIELD ATTRIBUTES command accepts two syntaxes: 


FIELD ATTRIBUTES (file number; field number; type; length; index) 

FIELD ATTRIBUTES (field pointer; type; length; index) 

You must use compiler directives to type the variables passed to the com- 
mand if they are not typed according to their use elsewhere in the data- 
base. 


Optimizing Code 


You can speed up your procedures by using compiler directives to type 
numeric variables as Integer or Longint or text variables as String. Here 
is a common example. 


Suppose you need to increment a counter using a local variable. If you 
don't declare the variable, 4D Compiler assumes that it is a Real. If you 
specify that it is a Longint, the compiled database would perform more 
efficiently. A Real takes 10 bytes of memory; but if you typed the counter 
a Longint, it would need only 4 bytes. Incrementing a 10-byte counter 
takes longer than incrementing a 4-byte one. Also, calculations on Reals 
are slower than calculations on integers. Calculations on Reals are per- 
formed in Apple’s SANE environment, and this takes longer than process- 
ing calculations on integers. 


NOTE: Introducing more compiler directives than necessary has no negative impact. 
Compiler directives are not translated when the database is compiled. 


Using Reals and Strings 


If you assign a real value to a variable that you declared an Integer or 

assign a string of 30 characters to a variable that was declared a 10-char- 
acter one, 4D Compiler assigns values according to your directives. If you 
assign a real number to an integer variable, it takes the integer part of the 
value. Similarly, if you assign a 30-character string to a variable typed as 
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a 10-character string, the compiler takes the first 10 characters. It does 
not regard either assignment as a type conflict. 


Here is an example. If you write: 


C_INTEGER (vinteger) 
vinteger:=2.5 


4D Compiler takes the integer part of the number (2 instead of 2.5). 


WARNING: In 4th DIMENSION versions preceding 2.1, the vInteger variable would 
have taken the value 2.5, and not 2. To avoid any surprises, retest your databases using 
2.1, compiled and uncompiled. 


Here is an example that deals with strings. In the following sequence: 
C_STRING (10;MyString) 

MyString:="It is a beautiful day" 

4D Compiler just takes the first ten characters of the constant, 

“It is a be”. 


Using Compiler Directives with the Interpreter 


Compiler directives are not required for databases that are not compiled. 
The interpreter automatically types each variable according to how it is 
used in each statement, and a variable can be freely retyped throughout 
the database. 


Because of this flexibility, it is possible that a database can perform dif- 
ferently in interpreted and compiled modes. For example, if you write: 


C_LONGINT (Myint) 
and elsewhere in the database, you write: 


Myint:=3.1416 

In the compiled database, the value 3 would be assigned to MyiInt. Nor- 
mally, the interpreter would assign the value 3.1416. This assignment 
would cause the same database to give different results in interpreted 
and compiled modes. 


Versions 2.1 (and above) of 4th DIMENSION contains a special feature 
that reduces the chances of discrepancies such as this. The 

4th DIMENSION interpreter uses compiler directives to type variables. 
When the interpreter encounters a compiler directive, it types the vari- 
able according to the directive. If a subsequent statement tries to assign 
an incorrect value (e.g., assigning an alphanumeric value to a numeric 
variable) the assignment will not take place. However, no error message 
will be generated. 





In the above example, MyiInt is assigned the same value (3) in both the 
interpreted and compiled modes, provided the compiler directive is inter- 
preted prior to the assignment statement. 


The order in which the two statements appear is irrelevant to the com- 
piler because it first scans the entire database for compiler directives. The 
interpreter, however, is not systematic. It interprets statements in the 
order that they are executed. That order, of course, can change from ses- 
sion to session, depending on what the user does. For this reason, it is 
important to design your database so that your compiler directives are 
executed prior to any statements containing variables that are declared. 


Where to Place your Compiler Directives 


Placing a compiler directive is a simple operation. Two strategies for glo- 
bal variables are open to you: 


m Use the directive in the procedure or script in which it first appears. 
Be sure to use the directive the very first time you use the variable, in the 
first procedure to be executed. 


m Declare your global variables in the Startup procedure 


NOTE: The 4th DIMENSION Language Reference states that the procedure that con- 
tains your compiler directives does not have to be executed. If the procedure is not exe- 
cuted, the compiler will use the directives to type variables (as usual) but you may get 
different results when using the database in interpreted and compiled modes. 


Local variables cannot be declared using this strategy because each local 
variable only exists in the procedure in which it appears. For local vari- 
ables, use the following strategy: 


m Declare your local variables in the procedure in which they appear. 


Local variables cannot be typed globally. The relevant compiler direc- 
tives should appear prior to the first use of the local variable in the pro- 
cedure. 


REMINDER: A global variable in 4th DIMENSION is a variable whose value is accessi- 
ble throughout the database. Its name always begins with one of the 26 letters of the 
alphabet. A local variable is a variable that exists only within a procedure. Its name 
begins with the $character. 
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The C_STRING Compiler Directive 


The C_STRING command uses a different syntax than the other directives 
because it accepts an additional parameter — the maximum string 
length. 

C_STRING (length; variable1 [;...; variableN}) 

Because C_STRING concerns fixed-length strings, it is natural to specify 
the maximum length of such strings. In a compiled database, you must 
specify the length of the string with a constant, rather than a variable. 
Here is an example. 


In an interpreted database, the sequence 


TheLength:=15 
C_STRING (TheLength;TheString) 


is acceptable. 


4th DIMENSION interprets Length, then replaces Length with its value in 
the C_STRING compiler directive statement. 


However, the compiler uses this command when typing variables with 
no specific assignment in mind. Thus, it is not in a position to know that 
TheLength equals 15. Not knowing the string’s length, it cannot keep a 
space for it in the symbol table. Therefore, with compilation in mind, a 
constant should be used to specify the length of the declared string of 
characters. For example, a statement such as this should be used: 


C_STRING (15;TheString) 

The same rule applies to declaring fixed string arrays, which are typed 
with the command: 

ARRAY STRING (length;array name;size) 


The parameter that indicates string lengths in the array must be a con- 
stant. 


NOTE: Do not confuse the length of an Alphanumeric field, which has a maximum of 
80 characters, with a fixed string variable. The maximum length of a string declared by 
a C_STRING directive, or belonging to an ARRAY STRING is between 1 and 255. 
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Summary 


This chapter provides an overall description of the compiler's behavior 
in its analysis of data types of variables. For a more detailed and practical 
understanding, we suggest that you read the next two chapters. They 
illustrate the statements in this chapter and provide: 


m A guide through potential conflicts of data types, and how to avoid 
them. This chapter is called “Typing Guide.” 


m Special notes about compilation for a group of 4th DIMENSION com- 
mands. 
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TYPING GUIDE 


This chapter contains further details about typing conflicts that can pre- 
vent a database from being compiled. The chapter is organized according 
to the type of object that generates the conflict. We consider the follow- 
ing types of objects: 


Global variables 
Local variables 
Arrays 

Layout variables 
Pointers 


External Procedures 


Reserved Variables 


Global Variables 


Type conflicts regarding global variables can be categorized as follows: 
Conflict between two uses 


n 
m Conflict between use and a compiler directive 
m Conflict resulting from implicit retyping 

(| 


Conflict between two compiler directives 


Conflict Between Two Uses 


The simplest data type conflict is one that stems from a single variable 
name designating two different objects. 


Assume you write: 

Variable:=5 

and in the same database, you write: 
Variable:=TRUE 


Theses two statements generate a data type conflict. Often the problem 
can be solved simply by renaming one of the variables. 





Conflict Between Use and a Compiler Directive 


Suppose you write 

Variable:=5 

and in the same application, you write: 

C_BOOLEAN (Variable) 

Because the compiler scans the directives first, it will type Variable as 


Boolean; but when it finds the statement “Variable:=5", it detects a data 
type conflict. 


You can solve the problem by renaming your variable or modifying the 
compiler directive. 


Using variables of different data types in one expression creates inconsis- 
tencies. The compiler points out incompatibilities. 


Here is a simple example. 


Bool:=TRUE ‘4D Compiler determines that Bool is data type Boolean 3 
C_INTEGER (Integer) RI. 
Integer:=3 “Assigning value compatible with compiler directive 19 
Var:=Integer+Bool ‘Operation using variables whose Pes: 


“data types are incompatible 


Conflict Stemming from Implicit Retyping = 


Some functions return variables of a very precise data type. Assigning the 
result of one of such variables to a variable already typed differently cre- 
ates a data type conflict. 


In an interpreted application, you can write: 


ident No:=Request ("Identification Number”) “Ident No is data type Text 

If (OK=1) 
ident No:=Num (ident No) “Ident No is now data type Real —i 
SEARCH ([Contacts]ID=Ident No) LE 


End if sa 

In this example, you create a type conflict in the third line. In some 1 

cases, you have to create an intermediate variable that uses a different 

name. In other cases, such as this one, your procedure can be structured 

differently. 

ident No:=Num (Request ("Identification Number")) ident No is data type Real _ ar 

If (OK=1) mire 
SEARCH ([Contacts]ID=Ident No) 

End if 
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Conflict Between Two Compiler Directives 


Declaring the same variable through two conflicting compiler directives 
constitutes a retyping. If, in the same database, you write: 


C_BOOLEAN (Variable) 
and 
C_TEXT (Variable) 


the compiler detects the conflict and reports an error in the error file. 
Typically, you can solve the problem by renaming one of the variables. 


A data type conflict can arise in the use of C_STRING if you modify the 
maximum string length. Thus, if you write: 

C_STRING (5;MyString) 

MyString:="Flour" 

C_STRING (7;MyString) 

MyString:="Flowers" 

the compiler identifies a conflict because it must provide an adequately- 
sized location when declaring String variables. 


The solution is to use only one compiler directive that gives the maxi- 
mum length, since the compiler accepts a shorter length. You can write: 
C_STRING (7;MyString) 

MyString:="Flour" 

MyString:="Flowers" 

If you like, you can use C_STRING (7;String) twice, i.e., 

C_STRING (7;MyString) 

MyString:="Flour" 

C_STRING (7;MyString) 

MyString:="Flowers" 

but it would be redundant. 
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Local Variables 


Data type conflicts concerning local variables are identical to those in 
global variables. The only difference is that consistency must be 
achieved only within a specific procedure or script. 


For global variables, conflicts occur at the general level of the database. 
For local variables, conflicts occur at the level of the procedure or script. 
For example, you cannot write in the same procedure: 


$Temp:="Flowers" 

and then 

$Temp:=5 

However, you can write: 

$Temp:="Flowers" 

in procedure P1, and 

$Temp:=5 

in procedure P2. Local variables are not globally typed. 


Conflicts in Array Variables 


Conflicts concerning an array are never size-related. As in uncompiled 
databases, arrays are managed dynamically. The size of an array can vary 
throughout procedures and you do not have to declare a maximum size 
for an array. Therefore, you can size an array to null, add or remove ele- 
ments, or delete the contents. 


You should follow the following guidelines when writing a database 
intended for compilation: 

= Do not change data types of array elements 

m Do not change the number of dimensions of an array 


w Fora string array, do not change character-string length 


REMINDER: Arrays are always global variables. Therefore, any declaration applies to 
the entire application. 
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Changing Data Types of Array Elements 


If you declare an array as Array Integer, it must remain an integer array 
throughout the database. 


If you write: 

ARRAY INTEGER (MyArray;5) 

ARRAY BOOLEAN (MyArray;5) 

the compiler cannot type MyArray. Simply rename one of the arrays. 


Changing the Number of Dimensions of an Array 


In an uncompiled database, you can change the number of dimensions 
of an array. When the compiler sets up the symbol table, one-dimen- 
sional arrays and two-dimensional arrays are managed differently. Con- 
sequently, you cannot redeclare a one-dimensional array as two- 
dimensional, or vice-versa. 


Therefore, in the same database you cannot have: 

ARRAY INTEGER (Array1;10) 

ARRAY INTEGER (Array1;10;10) 

However, you may write the following statements in the same applica- 
tion: 

ARRAY INTEGER (Array1;10) 

ARRAY INTEGER (Array2;10;10) “Note different array name 

And you can also write: 

ARRAY BOOLEAN (Array;5) 

ARRAY BOOLEAN (Array;10) * Resizes the array 

The number of dimensions in an array cannot be changed in a database. 
You can, however, change the size of an array. You can resize one array 
of a two-dimensional array. 


REMINDER: A two-dimensional array is, in fact, a set of several one-dimensional 
arrays. For more information, see the chapter “Arrays and Pointers” in the 
4th DIMENSION Language Reference. 
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String Arrays 


String arrays obey the same rules as fixed strings, and for the same rea- 
sons. 


If you write: 

ARRAY STRING (5;Array;10) 

ARRAY STRING (10;Array;10) 

the compiler detects a length conflict. The solution is simple: Declare the 
maximum string length. 4D Compiler automatically manages shorter 
length strings. 


Implicit Retyping 


While using commands such as COPY ARRAY, LIST TO ARRAY, ARRAY TO 
LIST, SELECTION TO ARRAY, ARRAY TO SELECTION, you may change, vol- 
untarily or not, the data type of elements, the number of dimensions, Or, 
in a String array, the string length — and you find yourself in one of the 
three situations previously mentioned. 


The compiler generates an error message; the required correction is usu- 
ally quite obvious. Examples of implicit array retyping are provided in 
the next chapter in the discussion of the array commands. 


Layout Variables 


Variables created in a layout (e.g., buttons, pop-up menus, and so forth) 
are always global variables. 


In an interpreted database, the data type of such variables is not impor- 
tant. However, in compiled applications it may have to be taken into 
consideration. The rules are, nevertheless, quite clear: 


m You can type layout variables using compiler directives, or 
m The compiler assigns the appropriate default data types 


The conventions used by the compiler in typing layout variables are 
given in this section. 


Layout Variables Typed as Numeric 


The following lavout variables are typed as Reals: Check box, Button, 
Highlight button, Invisible button, Radio button, Radio Picture, Ruler, 
Dial, and Thermometer. 
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You may explicitly declare these variables as Integer or Longint. There is 
an advantage to doing so: a Real requires 10 bytes, an Integer or a 
Longint only 4. 


The only possible data type conflict for one of these variables could arise 
if the name of a variable were identical to that of another variable 
located elsewhere in the database. In this case, rename the second vari- 
able. 


Graph Variable 


A graph area is automatically data type Graph. This variable never creates 
a data type conflict. The only possible data type conflict for a Graph-type 
variable could arise if the name of this variable were identical to that of 
another variable located elsewhere in the application. In this case, 
rename the second variable. 


External Object Variable 


An External Object is always a Longint. There can never be a data type 
conflict. The only possible data type conflict for an External Object vari- 
able could arise if the name of this variable were identical to that of 
another variable located elsewhere in the application. In this case, 
rename the second variable. 


Layout Variables Typed as Text 


There are four such variables: Non-enterable variable, enterable variable, 
pop-up menu, and scrollable area. 

These variables are divided into two categories: 

m Simple variables — Enterable and non-enterable variables 


m Display variables — Pop-up menus and scrollable areas 


Simple Variables 


Their default data type is Text. When used in scripts or procedures, they 
are assigned the data type selected by you. There is no danger of conflict 
other than a conflict resulting from assigning the same name to another 
variable. 
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Display Variables 


Pop-up menus and scrollable areas are only used to display the contents 
of arrays. There will be no problem if you follow the basic conventions 
concerning arrays as discussed earlier. 


Pointers 


When you use pointers in your database, you take advantage of a pow- 
erful and versatile 4th DIMENSION tool. The compiler preserves all the 
benefits of pointers. 


A pointer can point to variables of different data types. Do not create a 
conflict by assigning different data types to the same variable. 


Be careful not to change the data type of a variable to which a pointer 
refers. Here is an example of this problem. 


Variable:=5.3 
Pointer:=» Variable 
Pointer»:=6.4 


Pointer»:=FALSE 


In this case, your dereferenced pointer is a Real variable. By assigning it 
a Boolean value, you create a data type conflict. If you need to use point- 
ers for different purposes in the same procedure, make sure that your 
pointers are defined. Here is an example of the correct use of pointers. 


Variable:=5.3 

Pointer:=» Variable 

Pointer»:=6.4 

Bool:=True 

Pointer:=»Bool 

Pointer» :=False 

A pointer is always defined in relation to the object it refers to. That is 
why the compiler cannot detect data type conflicts created by pointers. 
In case of conflict, you will get no error message while you are in the 
typing phase or in the compilation phase. 


This does not mean that the compiler has no way of detecting conflicts 
that involve pointers. The compiler is capable of analyzing some uses of 
pointers with the Range Checking option. This option is discussed in 
detail in Chapter 3. 
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External Procedures 

External procedures can be located in four different places: 
m Inthe System file 

m In 4th DIMENSION 

m Inthestructure of your database 


m Inanexternal procedures file (proc.ext) located in the same folder as 
your database 


In any case, the compiler needs the procedure's definition, i.e., the num- 
ber of parameters and their data types. There is no danger of typing 
errors as soon as the compiler actually finds what you have declared in 
the database. 


Often, the simplest solution is to store your external procedures in the 
structure file of the database to be compiled. When the compiler dupli- 
cates the original database, it automatically copies the external proce- 
dures. If the externals are in a proc.ext file in the database folder or in the 
System file, the compiler does not duplicate the file, but it automatically 
takes into account the declarations of the procedures. 


If you place your externals in 4th DIMENSION, 4D Compiler asks you to 
specify the location of your external procedures during typing. It dis- 
plays the standard open-file dialog box. Click the document that con- 
tains the externals, and click the Open button. 


At that time, the compiler analyzes the definition of your procedure. 
Here too, there is no danger of confusion at the typing level if your calls 
are consistent with the declaration of the procedure. 


You can pass fewer parameters to an external procedure than it is expect- 
ing, provided the missing parameters are at the end. 
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Handling Parameter Passing 


The handling of the local variables, $0...$n, follows all the rules that 
have already been stated. As with all other local variables, their data type 
cannot be altered while the procedure executes. 


In this section, we examine two instances that could lead to data type 
conflicts: 

m When you actually require retyping. The use of pointers helps avoid 
data type conîflicts. 


m When you need to address parameters by indirection. 


Using Pointers to Avoid Retyping 


A variable cannot be retyped. However, it is possible to use a pointer to 
refer to variables of different data types. Here is an example to illustrate 
this. 


Consider a function that returns the memory size of a one-dimensional 
array. In all cases but two, the result is a Real; for Array Text and Array 
Picture, the memory size depends on values that cannot be expressed 
numerically. For more information, see the section “Managing Arrays,” 
in the 4th DIMENSION Language Reference. 


For Text and Picture arrays, the result is returned as a string of characters. 
This function requires a parameter: a pointer to the array whose memory 
size we want to know. 


There are two methods to carry out this operation: 


ms Workwith local variables without worrying about their data types; in 
such case, the procedure runs only in interpreted mode. 


m Use pointers, and proceed either in interpreted or in compiled mode. 
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° MemSize function, only in interpreted mode. 
$Size:=Size of array ($1») 
$Type:=Type ($1») 


Case of 
: ($Type=14) ‘Array Real 
$0:=8+($Size*10) °$0 is a Real (Numeric) 


: ($Type=15) ‘Array is Integer 
$0:=8+($Size*2) 

: ($Type=16) “Array is Long integer 
$0:=8+($Size*4) 


: ($Type=18) “Array is Text 
$0:=String (8+($Size*4) +("+Sum of text sizes") $0 is text 
:($Type=19) Array is Picture 
$0:=String (8+($Size*4) +("+Sum of picture sizes") 
End case 
In the above procedure, $0’s data type changes according to the value 
of $1; therefore, it is not compatible with the compiler. Here is how to 
write this procedure using pointers. 
° MemSize function in interpreted and compiled modes 


$Size:=Size of array ($1») 
$Type:=Type ($1») 


VarNum:=0 
Case of 
:($Type=14) “Array Real 
VarNum:=8+($Size*10) “VarNum is a Real 
:($Type=15 ‘Array Integer 
VarNum:=8+($Size*2) “VarNum is a Real 
:($Type=16) Array Longint 
VarNum:=8+($Size*4) ©’ VarNum is a Real 
: ($Type=18) “Array is Text 


VarText:=String (8+($Size*4) +("+Sum of text sizes”) 
:($Type=19) Array is Picture 
VarText:=String (8+($Size*4) +("+Sum of picture sizes") 
End case 
If (VarNum#0) 
$0:=»VarNum 
Else 
$0:=» VarText 
End if 


Here is the key difference between the two functions: 
m Inthe first case, the function's result is the expected variable 


m Inthe second case, the function's result is a pointer to that variable 


m 
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You simply dereference your result. 


Parameter Indirection 


4D Compiler manages the power and versatility of parameter indirec- 
tion. In interpreted mode, 4th DIMENSION gives you a free hand with 
numbers and data types of parameters. You retain this freedom in com- 
piled mode, provided you do not introduce data type conflicts and that 
you do not use more parameters than you passed in the calling proce- 
dure. 


To prevent possible conflicts, parameters addressed by indirection must 
all be of the same data type. 


This indirection is best managed if you respect the following conven- 
tion: If only some of the parameters are addressed by indirection, those 
parameters should be passed after the others. 


Within the procedure, an indirection address is formatted: $/$i}, where 
$i is a mumeric variable. ${$i} is called a generic parameter. 


Here is an example. Consider a function that takes values, adds them up, 
and returns the sum formatted according to a format that is passed as a 
parameter. Each time this procedure is called, the number of values to be 
added may vary. We must pass the values as parameters to the procedure 
and the format in the form of a character string. The number of values 
can vary from call to call. 


This function is called in the following manner: 


MySum ("##0.00";125.2;33.5;24) 


In this case, the calling procedure will get the string “182.70”, the sum 
of the numbers, and formatted as specified. The function's parameters 


must be passed in the correct order: First the format and then the values. 


Here is the function named MySum: 


$Sum:=0 

For ($i;2;Count Parameters) 
$Sum:=$Sum+${$i} 

End for 

$0:=String ($Sum;$1) 


This function can now be called in various ways: 
MySum ("##0.00";125.2:2:33.5;24) 

or 

MySum ("000";1;18:4;23;17) 
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As with other local variables, it is not necessary to declare generic param- 
eters by compiler directive. When required (in cases of ambiguity or for 
optimization), it is done using the following syntax: 


C_INTEGER (${4}) 

The command above means that all parameters from the fourth 
(included) on will be addressed by indirection. All will be data type Inte- 
ger. Data types of $1, $2, and $3 are irrelevant. 


NOTE: In Version 2, 4th DIMENSION replaced variable indirection in Version 1 with 
new tools: Arrays and pointers. Version 2 accepts the older procedures for compatibility 
reasons. Since the compiler was developed for Version 2, the performance of the faster 
and more powerful tools is optimized. If you use Version 1 indirection, change your pro- 
cedures accordingly. 


Reserved Variables 


Some 4th DIMENSION variables are assigned a data type and an identity 
by the compiler. Therefore, you can not create a new variable, a proce- 
dure, a function or an external procedure using any of these variables. 

You can test their values, and use them as you do in interpreted mode. 


System Variables 


Here is a complete list of 4th DIMENSION system variables with their data 
types. 


System Variable Type 

OK Longint 
Document String (255) 
FidDelimit Longint 
RecDelimit Longint 
Error Longint 
MouseDown Longint 
KeyCode Longint 
Modifiers Longint 
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Quick Report Variables 


When you create a calculated column in a report, 4th DIMENSION auto- 
matically creates a variable C1 for the first one, C2 for the second one, 
C3. and so forth. This process is performed in a transparent manner. 


If you use these variables in formulas, keep in mind that, like other vari- 
ables, C1, C2,...Cn cannot be retyped. 
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DETAILS ABOUT CERTAIN COMMANDS 
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4D Compiler expects that the usual syntactic rules for 4th DIMENSION 
commands are followed. In this respect, it does not require any specific 
modifications for databases that will be compiled. 


Some commands that affect a variable’s data type may lead to data type 
conflicts. Because some commands use more than one syntax, it is to 
your advantage to know which is the most appropriate one to select. 


The commands that fall into these categories are discussed in this chap- 
ter. They are grouped by topic in alphabetical order. 


Arrays 


Five 4th DIMENSION commands are used by the compiler to determine 
the data type of an array. They are: 

COPY ARRAY (from; to) 

SELECTION TO ARRAY (field; array) 

ARRAY TO SELECTION (array; field) 

LIST TO ARRAY (list;array; {linked array}) 

ARRAY TO LIST (array;list; {linked array}) 


COPY ARRAY 

The COPY ARRAY command accepts two array-type parameters. If one of 
the array parameters is not declared elsewhere, the compiler determines 
the data type of the undeclared array from the data type of the declared 
one. 


Such deduction is performed in both cases: 


m Thearray typed elsewhere is the first parameter. The compiler assigns 
the data type of the first array to the second array. 


m Thedeclared array is the second parameter. Here, the compiler assigns 
the data type of the second array to the first array. 


Because the compiler is strict about data types, COPY ARRAY can be 
performed only from an array of a certain data type to an array of the 


same type. 


Consequently, whenever you want to copy an array of elements whose 
data types are similar, that is, Integer, Longint and Real; or Text and 
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String, where fixed Strings are of various lengths, you have to copy the 
elements one by one. 


Suppose you want to copy elements from an Integer array to a Real array. 
You can proceed as follows: 


$Size:=Size of array (Arrint) 


ARRAY REAL (ArrReal;$size) “Set same size for Real array and Integer array 
For ($i;1;$Size) 

ArrReal{$i}:=ArrInt{$i} “Copy each of the elements 
End for 


Remember that you cannot change the number of dimensions of an 
array during the process. If you copy a one-dimensional array into a two- 
dimensional array, 4D Compiler generates an error message. 


SELECTION TO ARRAY and ARRAY TO SELECTION 


The default type for an undeclared array is Text. The undeclared array 
will be assigned the data type of the field specified in the command. 


If you write: 
SELECTION TO ARRAY ([MyFile]intfield;MyArray) 


the data type of MyArray would be Array Integer (assuming that IntField 
is an integer field). 


If the array has been declared, make sure that the field is of the same 
data type. Although Integer, Longint and Real are similar types, you may 
not consider them as equivalent. 


If an array was not previously declared and you apply one of the com- 
mands that includes a String-type field as a parameter, the default data 
type assigned to the array is Text. 


If the array was previously declared as String or Text, these commands 
will follow your directives. The same is true for Text-type fields: your 
directives have priority. 


LIST TO ARRAY and ARRAY TO LIST 


These commands apply only to two types of arrays: one-dimensional 
String arrays and one-dimensional Text arrays. 


Neither command requires that the array passed as a parameter be 
declared. 
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“Receive Variable example 
SET CHANNEL (12;"Document1") 
RECEIVE VARIABLE ($Type) 
Case of 
:($Type=0) 
RECEIVE VARIABLE ($String) ‘Processing variable received 
:($Type=1) 
RECEIVE VARIABLE ($Real) ‘Processing variable received 


:($Type=2) 
RECEIVE VARIABLE ($Text) ‘Processing variable received 


End case 
SET CHANNEL (11) 


NOTE: Values returned by the Type function are listed in the 4th DIMENSION 
Language Reference, under function Type. 


Data Entry 


Type (parameter) 


Because each variable in a compiled database has only one data type, this 
function may seem to be of no use. However, it can be useful when you 
work with pointers. For example, you may need to know the data type 

of the variable to which a pointer refers; due to pointer flexibility, one 

cannot always be sure to what object it points. 


Exceptions 

ON EVENT CALL (event procedure) 

ON SERIAL PORT CALL (serial procedure) 
ABORT 

IDLE 


A command has been added to 4th DIMENSION language to manage 
exceptions: the command IDLE. This command should be used when- 
ever you use the command ON EVENT CALL or ON SERIAL PORT CALL. 
This command could be defined as an event management directive. 


Only the kernel of 4th DIMENSION is able to detect a Macintosh event 
(mouse click, keyboard activity, and so forth). In most cases, kernel calls 
are initiated by the compiled code itself, in a way that is transparent to 
the user. 
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On the other hand, when 4th DIMENSION is waiting passively for an 
event — in a waiting loop for instance — it is clear that there will be no 
call. 


Here is an example: 


“MouseClick Procedure 
vTest:=True 
MESSAGE ("Somebody clicked the mouse") 


“Wait Procedure 

vTest:=False 

ON EVENT CALL ("MouseClick") 

While (Not(vTest)) “Event's waiting loop 


End while 
ON EVENT CALL ("") 


You would add the command IDLE in the following manner: 


“Wait Procedure 
vTest:=False 
ON EVENT CALL (MouseClick) 
While (Not(vTest)) 
IDLE “Kernel call to sense an event 


End while 
ON EVENT CALL ("") 


Macintosh Desktop 


Open Document 
Create Document 
Append Document 


Document references returned by these functions are of the data type 
Time. 


Math 

Mod (value;divider) 

The expression “25 modulo 3” can be written in two different ways in 
4th DIMENSION: 

Variable:=Mod (25;3) 

and 


Variable:=25%3 

The compiler sees a difference between the two: Mod applies to all numer- 
ics, while the operator % applies only to Integers and Longints (if the 
operand of the % operator exceeds the limits of the Longints, the 
returned result is likely to be wrong). Whenever possible, use %. 


On a List 
Subtotal (data) 
The Subtotal function does not initiate break processing in compiled data- 


bases. Use the BREAK LEVEL command to initiate break processing and 
the ACCUMULATE command to specify what to accumulate for subtotals. 


Strings 

Ascii (character) 

In interpreted mode, you can pass either a non-empty string or an empty 
string to this function. In compiled mode, you cannot pass an empty 
string. If you did so, the compiler would not be able to detect an error in 
compilation if the argument passed to Ascii is a variable. 


The Range Checking option displays a message if you use this function 
with an empty string. 


Structure Access 

Field (field pointer) or Field (file number; field number) 

File (file pointer) or File (file number) 

These two commands return results of different data types, according to 
the parameters passed to them: 

w Ifyou passa pointer to the File function, the result it returns is 

a number. 

m If you pass a number to the File function, the result it returns is a 
pointer. 


The two functions are not sufficient for the compiler to determine the 
data type of the result. In such case, t0 avoid any ambiguity, use a com- 
piler directive. 
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Variables and Miscellaneous 


Undefined (variable) 

SAVE VARIABLE (document; variable1; {...; variableN}) 
LOAD VARIABLE (document; variable1; {...; variableN}) 
CLEAR VARIABLE (variable) 

Get Pointer (variable) 

EXECUTE (formula) 

TRACE 

NO TRACE 


Undefined 


A variable can never be undefined in compiled mode. In a compiled 
database, all variables are initialized to nulls before the startup procedure 
runs. The Undefined function therefore always returns FALSE. If the com- 
piler encounters this function, it generates a warning. 


NOTE: The Undefined function enables you to determine whether you are running in 

compiled mode. Test any variable for definition immediately after opening the database. 
If the Undefined function returns TRUE, the database is not compiled; otherwise, it is 
compiled. 


SAVE VARIABLE and LOAD VARIABLE 


In interpreted mode, you can check that the document exists by testing 
if one of the variables is undefined after performing a LOAD VARIABLE. 
This is no longer feasible in compiled databases, since the Undefined func- 


tion always returns FALSE. 
This test can be performed in either interpreted or compiled mode by: 


m Initializing the variables that you will receive to a value that is not a 
legal value for any of the variables 

m Comparing one of the received variables to the initialization value 
after LOAD VARIABLE 





The procedure can be written as follows: 


Vari :="XXXXXX" ‘“YxxxxX" is a value that cannot be returned by LOAD 
Var2:="xXXXXX" “VARIABLE 

Var3:="xXXXxX" 

Var4:="xxXXXXX" 

LOAD VARIABLE ("Document";Vari :Var2;Var3;Var4) 


I (Vari="xXXXXX") “Document not found 
Else “Document found 
End if 

CLEAR VARIABLE 


This routine uses two different syntaxes in interpreted mode: 


CLEAR VARIABLE (variable) 
CLEAR VARIABLE (“a”) 


In compiled mode, the first syntax of CLEAR VARIABLE reinitializes the 
variable (set to null for a numeric; empty string for a character string or 
a text, and so forth), since no variable can be undefined in compiled 
mode. Consequently, CLEAR VARIABLE does not free any memory in 
compiled mode, except in three cases: Text, Picture, and Array type vari- 
ables. 


For an array, CLEAR VARIABLE has the same effect as a new array declara- 
tion where size is set to null. 


For an array whose elements are Integers, CLEAR VARIABLE (Array) has the 
same effect as one of the following expressions: 


ARRAY INTEGER (Array;0) “if it is a 1-dimensional array 
ARRAY INTEGER (Array;0;0) “if it is a 2-dimensional array 


The second syntax, CLEAR VARIABLE("a"), is incompatible with the com- 
piler, since compilers access variables not by name but by address. 
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Get Pointer is a function that returns a pointer to the parameter that you 
passed to it. 


Get Pointer 


Suppose you want to initialize an array of pointers. Each element in that 
array points to a given variable. Suppose there are twelve such variables 
named V1, V2,...V12. You could write: 


ARRAY POINTER (Arr;12) 
Arr(1}:=»VI 
Arr{2}:=»V2 


Arr{12}:=»V12 


You could also write: 


ARRAY POINTER (Arr;12) 
For (i;1;12) 
Arr{i};=Get Pointer ("V"+String (i)) 
End for 
At the end of this operation you get an array of pointers where each ele- 
ment points to a variable Vi. 


These two sequences are compilable. However, if the variables V1...V12 
are not used explicitly elsewhere in the database, the compiler is not able 
to type them. Therefore they have to be used or declared explicitly else- 
where. 

Such explicit declaration may be performed in two ways: 

m Bydeclaring V1...V12 through a compiler directive: 

C_LONGINT (V1;V2;V3...V12) 

m Byassigning these variables in a procedure: 


V1:=0 
V2:=0 


V12:=0 


EXECUTE 


This command — an historical one in 4th DIMENSION — offers benefits 
in interpreted mode that are not carried over to compiled mode. 


In compiled mode the procedure name passed as a parameter to this 
command would be merely interpreted. You miss, therefore, some of the 
advantages provided by the compiler and your parameter's syntax can- 
not be checked. Moreover, you cannot pass local variables as parameters 
to it. 


EXECUTE can be replaced by a series of statements. Here are 
two examples: 


Assume the following sequence: 


i:=FctLayout 
EXECUTE ("INPUT LAYOUT(Layout"+String (i)+")") 


It could be replaced with: 


i:=FctLayout 
VarLayout:="Layout"+String (i) 
INPUT LAYOUT (VarLayout) - 


Here is another example: 


$Num:=SelPrinter 
EXECUTE ("Print"+$Num) DA 
zii 


Here, EXECUTE can be replaced with Case of: 


Case of 
:(&Num=1) | 
Print1 ssi 
:(BNum=2) 
Print2 
:(fNum=3) 
Print3 a 


siva 


End case 


The command EXECUTE can always be replaced. Because the procedure 
to be executed is chosen from the list of the database’s global procedures, 
and there is a finite number of them. Consequentily, it is always possible 
to replace EXECUTE with either Case of or with another command. Fur- 
thermore, your code will execute faster. 








TRACE and NO TRACE 


These two commands are used in the debugging process. They serve no 
purpose in a compiled database. However, you can keep them in your 
procedures; they will simply be ignored by the compiler. 


Pointers with the Following Commands 


ADD TO SET 

GOTO RECORD 
GOTO SELECTED RECORD 
APPLY TO SELECTION 
LOAD SET 

SEARCH 

SEARCH SELECTION 
SEARCH BY FORMULA 
DIALOG 

EXPORT TEXT 
EXPORT DIF 

EXPORT SYLK 
CREATE EMPTY SET 
OUTPUT LAYOUT 
INPUT LAYOUT 
GRAPH FILE 

PRINT LAYOUT 

PRINT LABEL 

IMPORT TEXT 
IMPORT DIF 

IMPORT SYLK 
MERGE SELECTION 
CREATE SET 

SORT SELECTION 
PAGE SETUP 


These commands have one feature in common: they all accept an 
optional first File parameter and the second parameter can be a pointer. 


In compiled mode, it is easy to retain the optional File parameter. How- 
ever, the compiler makes an assumption whenever the first parameter 
passed to one of these commands is a pointer. Since it doesn't know what 
the pointer is referring to, it assumes that it is a file pointer. 


For example, consider the SEARCH command. It has the following syn- 
tax: 

SEARCH ({file};search argument;{*}) 

where the first element of the search argument must be a field. 
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When you write: 

SEARCH (FieldPtr»=True) 

the compiler expects a symbol that stands for a field as the second ele- 
ment in the argument. In fact, it finds the sign “=”. ]t will generate an 
error message. 

On the other hand, if you write: 

SEARCH (FilePtr»;FieldPtr»=True) 

or 

SEARCH ([File];FieldPtr»=True) 

you remove all ambiguity. 


If the first parameter to one of these commands is a dereferenced pointer, 
it must point to a file. 
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It is difficult to state once and for all a “good-programming” method. But 
we wish to stress again the advantages of well structured programs. The 
capacity for structured programming in 4th DIMENSION can be a great 
help. 


The compilation of a well-structured database can yield much better 
results than the same effort performed in a poorly-designed one. For 
instance, if you write a generic procedure to manage n scripts you will 
get higher quality results, in interpreted as well as in compiled mode, 
than in a situation where the n scripts comprise n times the same set of 
statements. In other words, the quality of your programming does have 
an impact on the quality of the compiled code. 


You gradually improve your code under 4th DIMENSION with practice. 
Frequent use of the 4D Compiler gives you corrective feedback that 
enables you to reach instinctively for the most efficient solution. 


In this chapter, we offer some advice and a few tricks that will save you 
time in performing simple, recurring tasks. 


Using Compiler Directives to Optimize Code 


Compiler directives can help you speed up your code considerably. 
When typing variables on the basis of their use, the compiler uses the 
widest data type possible so as not to penalize you. For example, if you 
don't type the variable defined by the statement: Var:=S, the compiler 
will type it as Real, even if it could be declared an Integer. 


Use compiler directives wherever appropriate to type variables as Integer, 
Longint, or String. 


Numeric Variables 


The default data type that the compiler gives numeric variables is Real. 
But calculations performed on a Real are slower than on an Integer. If 
you know that a numeric variable will always be an integer, it is to your 
advantage to declare it through the compiler directives C_INTEGER or 
C_LONGINT. 


It is good practice, for instance, to declare your loop counters as Integers. 
Compare the execution times of an empty loop in the following two 
instances: 

For ($i;1;50000) 

End for 


If $i is not declared by compiler directive (i.e., $i is Real), the time is 
19 seconds. If $i is declared by compiler directive (C_INTEGER), it is an 
instantaneous loop. 


NOTE: These speeds vary according to the model of your Macintosh. 


Some 4th DIMENSION functions return Integers (e.g., Ascii). If you assign 
the result of one of these functions to an untyped variable of your data- 
base, 4D Compiler types it as Real rather than Integer. Remember to 
declare such variables by compiler directive whenever you are sure that 
they will not be used in a different context. 


Here is a simple example. The function that returns a random value 
within a given range may be written: 

$0:= Random % ($2-$1+1)+$1 

and it will always return an integer. 

Written this way, the compiler will type $0 as Real rather than Integer or 


Longint. It is preferable, therefore, to include a compiler directive in the 
procedure. 


C_LONGINT ($0) 
$0:= Random % ($2-$1+1)+$1 


The value returned by the procedure will take less space in memory and 
the procedure will be much faster. 


Buttons are a specific case of a Real that can be declared as Longint. 


Strings 

The default type assigned to alphanumeric variables is Text. If you write: 
MyString:="Hello" 

MyString would be typed as a Text variable by the compiler. 

If this variable will be processed frequently, it is worthwhile to declare it 
using the directive C_STRING. Processing is much faster with String type 


variables that have a defined maximum length than with Text variables. 
Keep in mind the rules governing the behavior of this directive. 
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NOTE: If you want to test the value of a character, make the comparison on its Ascii 
function rather than on the character itself. The regular character comparison procedure 
considers all of the character's alternatives, such as diacritical marks. 


Various Observations 


This section contains comments on two-dimensional arrays, fields, and 
pointers. 


Two-dimensional Arrays 


The processing of two-dimensional arrays is better managed if the sec- 
ond dimension is larger than the first. 


For instance, an array declared as: 
ARRAY INTEGER (Array;5;1000) 


will be better managed than an array declared as: 
ARRAY INTEGER (Array;1000;5). 


Fields 


Whenever you need to perform several calculations on a field, you can 
improve performance by storing the value of that field in a variable and 
performing your calculations on the variable rather than the field. 


Consider the following procedure: 


Case of 
:([Contacts]City="Saratoga") 
Ship:="Blue" 
:([Contacts]City="Reno") 
Ship:="Red" 
:([Contacts]City="Boston") 
Ship:="FedEx" 
End case 


This procedure will take longer to execute than if it were written: 


$Dest:=[Contacts]City 
Case of 
:($Dest="Saratoga") 
Ship:="Blue" 
:(Dest="Ren0") 
Ship:="Red" 
:(fDest="Boston") 
Ship:="FedEx" 
End case 


If code such as this is placed in a loop and executed repeatedly, the dif- 
ference in performance could be substantial. 


Pointers 


As is the case with fields, it is faster to work with variables than 

on dereferenced pointers. Whenever you need to perform several calcu- 
lations on a variable referenced by a pointer, you can save time by stor- 
ing the dereferenced pointer in a variable. 


For instance, suppose you use a pointer to refer to a field or to a variable, 
MyPtr. Then you want to perform a set of tests on the value referenced 
by MyPtr. You could write: 


Case of 
:(MyPtr»=1) 
‘Sequencet 
:(MyPtr»=2) 
‘Sequence? - 


End case 
The set of tests is performed faster if it were written: sl 


$Temp:=MyPtr» 2 ci 
Case of ; Le) 
:(STemp=1) s 
‘Sequencet 
:($Temp=2) 
“Sequence2 


End case 


Using Comments 


Some of the tricks and shortcuts we suggest may render your code less 
intelligible to others, and even to yourself later on. Consequently, use 7 
comments liberally. Comments are ignored by the compiler and do not 

appear in the compiled code. While comments tend to slow down an 

interpreted database, they have no effect on the execution time of a 

compiled database. 
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4D COMPILER MESSAGES 





This appendix lists the messages that can be generated by 4D Compiler. 
The following types of messages are described: 


m Warnings 
Advanced Warnings 
Errors 


Range checking messages 


Compiler messages 


Warnings, advanced warnings, and errors are listed in the error file and 
are displayed in 4th DIMENSION during interactive debugging. 

Range checking messages are displayed in an alert dialog box while the 
compiled database is running. Compiler messages refer to the perfor- 
mance of the compiler and are displayed in an Alert dialog box while the 
compiler is running. 


NOTE: The list of these messages may not be complete because it was written while 
4D Compiler was under development. Consult the Read Me file on your program disk for 
any supplemental information. 


Warnings 


These messages are generated during the typing phase of the compiler. 
In this section, each message is accompanied with an example of the 
problem. 


Pointer in COPY ARRAY 
COPY ARRAY (Pointer»; Array) 


Pointer in SELECTION TO ARRAY 


SELECTION TO ARRAY (Pointer»; MyArray) 
SELECTION TO ARRAY ([MyFile] MyField; Pointer») 


Pointer in ARRAY TO SELECTION 
ARRAY TO SELECTION (Pointer»; [MyFile] MyField) 


Pointer in LIST TO ARRAY 
LIST TO ARRAY ("List"; Pointer») 


Pointer in ARRAY TO LIST 
ARRAY TO LIST (Pointer»:"List") 


Using pointer in declaring an array 
ARRAY REAL (Pointer»;5) 


The command ARRAY REAL (Array; Pointer») does not generate this warn- 
ing. The value of the dimension of an array doesn't have any influence 
on its own type. In this example, the array referred to by the pointer 
must have been defined elsewhere. 


Use of Undefined is not advised 
If (Undefined (Variable)) 
The Undefined function always returns FALSE in a compiled database. 


Advanced Warnings 13 


These messages are generated only if you select the Advanced Warnings ca 
option in the Options window. If requested, these warnings appear in 
the error file. 


ii 
ti 


ta 


The pointer used in this command must refer to an Alphanumeric value 


Pointer»<2>:="a" 


= d 


The pointer used in this command must refer to an Integer, a Long Integer, or 
a Real value. 


MyString<Pointer»>:="a" 


An array index must be an Integer, Long Integer, or Real Number 
ALERT (MyArray{Pointer»}) 
where the pointer refers to an element in a text or string array. 
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Error Messages 


These messages are generated in the typing phase and are written to the 
error file. Each message is accompanied by an example. 


These messages are grouped by topic. The topics are: 
Typing 

Syntax 

Parameters 

Operators 


External Procedures 


General Errors 


Typing 


The assignment creates a type conflict 


MyReal:=12.3 “MyReal is Real 
MyBoolean:=TRUE “MyBoolean is Boolean 
MyReal:=MyBoolean “Cannot assign a Boolean to a Real variable 


Changing the length of a string 

C_STRING (3;MyString) 

C_STRING (5;MyString) 

Changing the number of dimensions of an array 


ARRAY TEXT (MyArray;5;5) 
ARRAY TEXT (MyArray;5) 


Declaring an array without indexes 
ARRAY INTEGER (MyArray) 


Expecting a global variable 
COPY ARRAY (MyArray;"") 


Expecting a numeric constant 
C_STRING (Variable;MyString) 








The type of the variable is unknown 
This variable is used in the procedure: 


The type of variable can't be determined. A compiler directive may be 
necessary. 


Expecting a text constant 


MyVar := "The weather is nice" 


The following procedure is unknown: 


The line contains a call to a procedure that doesn't exist or no longer 
exists. 


The length of the character string must be between 1 and 255 
C_STRING (325;MyString) 


The variable Variable is not a procedure 
Variable (1) 


The variable Variable is not an array 
Variable{5} := 12 


The result of the function is incompatible with the expression 
Text := "Number" + Num (i) 


The data types of the variables in the expression are incompatible 
Integer := MyDate*Text “Cannot multiply a date by a text variable 


The index of ${} is not numeric 

$i := "3" “$i is type Text 

${S$i}:= 5 

The index of an array is not numeric 

IntArray {"3"} (= 4 “The index is type Text 


Retyping of the variable Variable of type Text to a numeric type 
Variable := Num (Variable) 
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Retyping an array from Integer array to a Text array 


ARRAY TEXT (IntArray;12) 
if IntArray was declared elsewhere as an Integer array. 
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Only pointers can be followed by the sign 
Variable» := 5 
if Variable is not of the type Pointer. 


An array is always a global array 


ARRAY INTEGER ($Array;5) 
The name of an array always starts with a letter of the alphabet. It cannot 
begin with the $ character. 


Using the Text variable Variable as a numeric variable 


Variable := 3.5 


Using a field of the incorrect type 
Variable := [MyFile]MyDate 
where [MyFile]MyDate is a Date field and Variable is numeric 


Syntax 


The function does not return a pointer 
Variable := Num ("The weather is nice")» 
It is not possible to dereference this function 


Syntax error 


If (Boolean) 


End For “Should be End If 


A closing curly bracket } is missing 


The line contains more opening brackets than closing brackets. 


An opening curly bracket { is missing 
The line contains more closing brackets than opening brackets. 
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A closing parenthesis ) is missing 


The line contains more opening parentheses than closing parentheses. 


An opening parenthesis ( is missing 


The line contains more closing parentheses than opening parentheses. 


Expecting a field 
If (Modified (Variable)) 
The Modified function expects a field. 


Expecting an opening bracket { 
C_INTEGER (Array 2) 
Array(2):=1 

Expecting a variable 
C_INTEGER ([MyFile]MyField) 


Expecting a numeric constant 
C_INTEGER (${"3"}) 


Expecting a semicolon 
COPY ARRAY (Array1 Array2) 


Expecting the closing character reference operator 2 
MyStrings3 := "a" 


Expecting the opening character reference operator < 


MyString3> := "a" 


The expression following If must be Boolean 
If (MyReal) 
if MyReal is a numeric variable. 


The expression is too complex 


Divide your statement into several shorter statements. 
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The procedure contains more than 600 different cases or more than 
100 If...End if structures. 


Procedure is too complex 


Reference to an unknown field 


Your procedure, possibly copied from another database, contains an 
expression that refers to a non-existent field. 


Reference to an unknown file 


Your procedure, possibly copied from another database, contains an 
expression that refers to a non-existent file. 


A pointer cannot be defined in this expression 


Pointer := » Variable + 3 


Incorrect use of the character reference operator 


MyReal<3= or MyString<Variable=> 
where MyReal is a numeric variable and Variable is not a numeric vari- 
able. 


Parameters 


This result of the function cannot be a parameter of this procedure 


MyProcedure (Num(MyString)) 
if MyProcedure expects a Boolean expression. 


This value cannot be a parameter of this procedure. 


MyProcedure (3+2) 
if MyProcedure expects a Boolean expression. 


Type conflict regarding $0 


C_INTEGER ($0) °$0 is Integer 
$0 := FALSE °$0 is now Boolean 


Type conflict regarding the generic parameter ${} 
C_INTEGER (${3}) 
For ($i;3;5) 

${$i} := String ($i) ‘${Si} is now Text 
End For 
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The command does not accept a parameter 


Current Date (MyDate) 


The command requires at least one parameter 
DEFAULT FILE 


The variable MyString cannot be a parameter of this procedure 
MyProcedure (MyString) 
if MyProcedure is expecting a Boolean parameter. 


The type of the parameter $1 in the called procedure is different than the type 
of the parameter in the calling statement 


Calculate ("3+2") 
with the directive C_INTEGER($1)in Calculate. 


The parameter is type Text 


The data type of the parameter passed doesn't match the type of parameter 
expected 


Print ("LaserWriter") 
if in the procedure Print, $1 is numeric. 


Retyping a numeric parameter $1 to text type 
$1 := String ($1) 


A parameter cannot be an array 
MyProc (MyArray) 
To pass an array in a procedure, you need to pass a pointer to the array. 


A parameter cannot be used in calling this command 
RECEIVE VARIABLE ($1) 


Operators 


Addition cannot be performed on Boolean fields. 
Boolean2 := Booleant + TRUE 


Not expecting the > operator 
SEARCH ([MyFile];[MyFile]MyField=0;>) 
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The two arguments are not comparable 


If (Number = Picture2) 
where Number is a LongInt and Picture2 is a Picture. 


Negation cannot be used in this expression 
Boolean := -FALSE 


External Procedures 


The external procedure MyExternal is poorly defined 


The definition of the external routine is incorrect. 


The number of parameters passed to the external routine is too large 


General Errors 


Two procedures have the same name: Name 


To compile your database, all of the global procedures must have differ- 
ent names. 


Internal error No. xx 


If this message appears, call ACIUS or ACI Technical Support and report 
the error number. 


Cannot determine the type of Variable. 
This variable is used in the P1 Procedure. 


The Variable type cannot be determined. A compiler directive is neces- 
sary. 


The database contains more than 32K of global variables 


You must reduce the number of global variables. Consider using local 
variables. This message gives the amount of memory used by your global 
variables, except for arrays and fixed strings (declared by the C_STRING 
directive). 


REMINDER: Picture and text variables account for only 4 bytes each. 











The database contains more than 32K of local variables 


You must reduce the number of local variables in the procedure. This 
message gives the amount of memory used by your local variables, 
except for fixed strings (declared by the C_STRING directive). 


The procedure is larger than 32K 


Divide your procedure into smaller procedures. Chances are you are not 
writing tight code. 


The original procedure is damaged 
The procedure is damaged in the original structure. Delete it or replace it. 


4th DIMENSION command is unknown 


The procedure is damaged or the version of the compiler you are using 
was released before the command was added to 4th DIMENSION. 


Retyping the variable Variable in the format Format 


The message appears if you give, for example, the name OK to a variable 
of the type Graph in a layout. 


A function and a variable have the same name: Name 


Rename either the function or the global variable. 


An active object has the same name as a function: Name 


Rename either the active object or the function. 


An external procedure and a variable have the same name: Name 


Rename either the external procedure or the variable. 








Range Checking Messages 


These messages are displayed in 4th DIMENSION while the compiled 
database is running. These messages appear in the following window: 





Array capacity exceeded 


MyArray{17} := 2.3 

MyArray is an array with 5 elements at the time the above statement is 
executed. This message will appear if you try to access the {17} element 
in the array. 


The parameter cannot be passed. 


Using the $4 local variable when only three parameters have been passed 
to the current procedure. 


The pointer is not correctly initialized. 
MyPointer» := 5 
if MyPointer hasn’t yet been initialized. 


String in which the maximum length is too short. 


C_STRING (5;MyString1) 

C_STRING (10;MyString2) 

MyString2 := "TheString" 

MyString1 := MyString2 “ String2 has 9 characters, but String1 can store only 5 


The string index isn't valid (too large or negative). 

i:=30 

MyString<i> := MyString2 

The passed string in the parameter is empty or not initialized. 


MyString := "" 
Number := Ascii (MyString) 








Compiler Messages 


When its work environment is not optimal, 4D Compiler displays mes- 
sages that encourage you to improve its environment. These messages 
are displayed in the alert box shown below. 


Error 
There is not enough memory allocated to 
the application to run properiy. 


Rction 


If you are using MultiFinder, allocate more 
memory to the application. 





The Error area describes the problem. The Action area describes a way to 
fix it. 
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CUSTOMIZING APPLICATION ICONS 





Using 4D Compiler, you can merge your database with a 4D Runtime to 
create a stand-alone (double-clickable) application. You can do this sim- 
ply by selecting the option “Merge with Runtime” in the Options win- 
dow. For complete information about this option, see Chapter 2. 


When you merge your database with a runtime, 4D Compiler creates a 
stand-alone application with a generic application icon. You can cus- 
tomize this icon by following the procedure described in this appendix. 
You can also customize the icons for all the other documents that are cre- 
ated by a 4th DIMENSION database, i.e., the data file, quick reports, labels, 
saved searches, and so forth. 

This procedure uses: 

m Aresource editor, such as ResEdit"* 

m The Resources database, located on your 4D Compiler program disk 


m The uncompiled version of your database 


NOTE: ResEdit is a resource editing utility available from Apple Computer, Inc. This 
appendix assumes you are familiar with ResEdit. 


To customize your database icon, follow these steps: 


1. Copy the Resources database to your hard disk and open the struc- 
ture file using ResEdit. 


2. Copy the following resources from Resources to the structure file 
of the database to be compiled. 


m SIG* 

ms BNDL 

m FREF 

m ICN# 

Use standard copy and paste operations. 


NOTE: The FREF resource must not be modified. 


In the next series of steps, you will specify the Creator of your applica- 
tion. 
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3. Open the BNDL resource and replace the OwnerName with the 
4-character Creator for your application. 

The Creator must be different from the Creator of any other Macintosh 
application on your hard disk. If you inadvertently use the Creator of an 
existing application, the Finder might use the other application's icon 
instead of yours. 


If you intend to market your application, you need to check with Apple 
Computer, Inc. to ensure that your Creator is unique, i.e., not used by 
any other published Macintosh application. 

4. Open the SIG* resource and enter the 4-character Creator for your 
application. 


In the next series of steps, you will use ResEdit to customize your appli- 
cation’s icon. 


5. Open the ICN# resource. 


6. Open the icon with the identification number 128. 


ResEdit opens an editing window in which you can edit the icon. The 
bit-map on the left is the icon; the bit-map on the right is its “mask.” 
7. Modify the icon as you like. 

8. When you finish modifying each resource, save your changes by 
choosing Save from the File menu and close the window belonging 
to that resource. 

This step completes the process of customizing your application's icon. 
You can also customize the other files that are created by your applica- 
tion while it is running — the data file, quick reports, labels, searches, 
and so forth. 


To customize the icons belonging to these files, follow these steps: 

1. Open the appropriate ICN# resource and modify the icon using 
the bit-map editing tools. 

2. When you have finished customizing each icon, choose Save from 
the File menu. 

3. Close your application and quit from ResEdit. 


You are now ready to compile your database with the Merge with 
Runtime option. 


After the compiler creates your custom application, rebuild the desktop. 
In this process, the Finder adds your custom icons to its desktop file. 
After the desktop is rebuilt, your custom icons will appear. 





hei 











NOTE: You rebuild your desktop by choosing Restart from the F inder's Special menu and 
holding down the Option and % keys. A dialog box will ask you whether you want to 
rebuild your desktop. 
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